%\pagelayout{normal,twoside}
%\textheight 8in \textwidth 6in\topmargin 0.0in
%\documentstyle{article,11pt}
\documentstyle[11pt,twoside]{article}
\setlength{\textheight}{8in}
\setlength{\textwidth}{6in}
\setlength{\topmargin}{0in}
\oddsidemargin 0pt
\evensidemargin 0pt
\hyphenation{pre-sents}
\parskip 4pt
\begin{document}
\font \smcaps=amcsc10
\font \bldcn=ambc12
\font \eighttt=amtt8
\newcommand{\filename}[1]{{\tenrm#1}}
\newcommand{\key}[1]{\fbox{\eighttt#1}}
\newcommand{\emphasize}[1]{{\sl#1\/}}
\newcommand{\irafname}[1]{{\bf#1}}
\newcommand{\taskname}[1]{{\sl#1\/}}
\newcommand{\reference}[1]{{\it#1\/}}
\newcommand{\comptype}[1]{{\tt#1}}
\newcommand{\usertype}[1]{{\bldcn#1}}
\newcommand{\upa}{{\tt \char94}}
\newcommand{\lbox}{{\tt \char91}}
\newcommand{\rbox}{{\tt \char93}}
\newcommand{\bsl}{{\tt \char92}}
\newcommand{\pipe}{{\tt |\ }}
\newcommand{\pluseq}{$+\!=$}
\newcommand{\minuseq}{$-\!=$}
\newcommand{\timeseq}{$*\!=$}
\newcommand{\diveq}{$/\!=$}
\newcommand{\concateq}{$//\!=$}
\newcommand{\ppind}{\hspace*{17pt}}
\begin{titlepage} \vspace*{1.0in}
\begin{center} \huge
DRAFT\\ \vspace*{0.5in} \large \bf
A User's Introduction to the IRAF Command Language \\ \medskip
Version 2.3 \\
\bigskip
\smcaps Peter MB Shames\\
\tenrm Space Telescope Science Institute\\
\medskip
\smcaps Doug Tody\\
\tenrm National Optical Astronomy Observatories\\
\vskip 1cm
Revised -- \today\\ \vskip 1cm
\bldcn ABSTRACT\\ \medskip
\end{center} \large
\begin{quotation} \noindent
This tutorial introduction to the IRAF Command Language
presents an overview of the use and features of the language.
The discussion is aimed toward the first-time
user and describes the execution of tasks from the Command
Language. The focus is the Command Language itself;
the many packages and tasks that compose the IRAF system and the
SDAS packages from STScI are described elsewhere. The emphasis is
on using the Command Language to run existing programs, although
sections are included that describe the addition of new tasks
of one's own making. A quick guide to language features and facilities
and to the suite of reduction and analysis packages currently available
is provided in the Appendices.
\end{quotation}
\end{titlepage}
\pagestyle{empty}
\newpage
\thispagestyle{empty}
\begin{center} \vspace*{1in}
\large About the Authors
\end{center}
\vskip 1cm
\rm
\noindent
Peter Shames is Chief of the Systems Branch at STScI, and along with Jim Rose
and Ethan Schreier, was one of the key persons responsible for the selection
of IRAF as the command language and operating environment for the STScI
Science Data Analysis System (SDAS) in December of 1983. Since that time,
Peter has supervised the VMS/IRAF development effort at STScI, overseeing the
implementation of the VMS/IRAF kernel, the initial port of IRAF to VMS,
and the development of version 2.0 of the IRAF command language.
Peter wrote the original CL User's Guide (version 2.0).
\vskip 0.5cm
\noindent
Doug Tody is the originator and designer of the IRAF system (including the CL)
and has been Chief Programmer of the IRAF project since the inception of the
project at KPNO (now NOAO) in the fall of 1981. As Chief Programmer, Doug has
written virtually all of the IRAF system software with the exception of the
VMS/IRAF kernel and the original CL 1.0 (which was written by Elwood Downey).
Since 1983 Doug has been head of the IRAF group at NOAO, overseeing the
development of the NOAO science applications software while continuing work
on the IRAF systems software, and coordinating the effort with STScI.
\newpage
\thispagestyle{empty}
\begin{center} \vspace*{1in}
\large Acknowledgements
\end{center}
\vskip 1cm
\rm
\noindent
The authors wish to acknowledge the efforts of the many people who have
contributed so much time, energy, thought and support to the development
of the IRAF system. Foremost among these are the members of the IRAF
development group at NOAO (Lindsey Davis, Suzanne Hammond, George Jacoby,
Dyer Lytle, Steve Rooke, Frank Valdes, and Elwood Downey, with help from
Ed Anderson, Jeannette Barnes, and Richard Wolff) and members of the VMS/IRAF
group at STScI (Tom McGlynn, Jim Rose, Fred Romelfanger, Cliff Stoll,
and Jay Travisano). The sharp editorial eye and sharper pencil of
Chris Biemesderfer have made major contributions to the clarity and style
of this document.
\vskip 0.3cm
\noindent
The continuing patience and understanding of members of the scientific
staff at both institutions has been essential to the progress that has
so far been achieved. A major software project such as IRAF cannot
be attempted without the cooperation of many individuals, since the
resources required must inevitably place a drain on other activities.
In particular, the support and encouragement of Harvey Butcher,
Garth Illingworth, Buddy Powell, Steve Ridgway and Ethan Schreier has
been invaluable. Mention should also be made of Don Wells, who started
in motion in the latter part of the last decade the process which eventually
led to the creation of the IRAF system.
\begin{flushright}
Peter Shames \\
Doug Tody
\end{flushright}
\clearpage
\pagestyle{myheadings}
\markboth{CL User's Guide (DRAFT)\hspace*{2.1in}}
{\hspace*{2.1in}CL User's Guide (DRAFT)}
\pagenumbering{roman}
\tableofcontents
\thispagestyle{empty}
\newpage
\pagestyle{myheadings}
\markboth{CL User's Guide (DRAFT)\hspace*{2.1in}}
{\hspace*{2.1in}CL User's Guide (DRAFT)}
\pagenumbering{arabic}
\begin{center} \vspace*{0.5in} \large \bf
A User's Introduction to the IRAF Command Language \\ \medskip
Version 2.3 \\
\bigskip
\smcaps Peter MB Shames\\
\tenrm Space Telescope Science Institute\\
\medskip
\smcaps Douglas Tody\\
\tenrm National Optical Astronomy Observatories\\
\vskip 1cm
\end{center} \rm
\section*{How to use this book}
\ppind
This document is an introduction to the IRAF
Command Language (CL), and is designed to be a tutorial
for the first-time user. The examples presented in the text can
(and should) be tried at a terminal. Although this text is
large enough to be a bit daunting at first, it can be tackled
in easy stages, and need not all be read before trying the system.
A basic knowledge of computer systems is assumed.
The first three chapters form an introductory section
which covers the most basic elements of IRAF. Reading through these,
preferably while seated near a terminal where the examples may be tried
out, is the recommended entry into the IRAF world. The fourth and fifth
chapters deal with the interface between IRAF and the host system,
and with some of the more advanced uses of IRAF for normal data
analysis activities. These chapters will be of use once you are familiar
with the basic environment and the examples here are also designed
to be tried out on a live system. The rest of this document is for the
more adventurous user, who is not happy until he can say \usertype{doit}
and get \irafname{it} done to a turn. Try some of these last examples
when you are ready to customize IRAF for your own particular uses.
In spite of its size, this document
is not intended to be a complete guide to using and programming
the IRAF system, but is an introduction to many of the functions
of the CL and a quick guide to other sources of more detailed information.
The CL is described as the user's interactive interface to the system,
and simple commands that use the terminal for starting and controlling tasks
and for customizing the environment are presented.
Development of simple functions in the CL are covered briefly here, but
coverage of all the details of programming in the CL or in the
IRAF environment is beyond the scope of this document.
A reasonable amount of documentation is accessible at the terminal via
the online help facilities, which are described here as well.
More extensive details of the CL may be found in the manual pages for the
\taskname{language} package, in the \reference{CL Programmer's Manual} and
in \reference{The IRAF User's Guide}.
Details of programming in the IRAF system itself are described
in the \reference{Programmer's Crib Sheet for the IRAF Program Interface},
in the \reference{Reference Manual for the IRAF Subset Preprocessor Language}
and in other documents referred to in the last section of this text,
however, these documents are somewhat dated and most of the documentation
planned for the IRAF programming environment remains to be written.
Documentation in the form of manual pages for the suites of applications
packages being developed at both NOAO and STScI are available both online
and in printed form.
\section{Introduction}
\subsection{An Overview of IRAF}
\ppind
The Image Reduction and Analysis Facility (IRAF) has been designed to
provide a convenient, efficient and yet portable system
for the analysis of images and other classes of data. While the
system has been designed for image data, and for astronomical image data
in particular, it has general facilities that can be applied to many
other classes of data. Some of the functions that are
provided are quite specialized, dealing as they do with the
characteristics of specific instruments, but others are generalized
functions for plotting data, computing statistics, processing lists, and
performing other functions that are common to
data processing tasks in many other fields.
The runtime IRAF system consists of four basic pieces:
\begin{itemize}
\item Command Language - which provides the user interface to the system.
\item Applications Packages - that are the real data analysis algorithms.
\item Virtual Operating System (VOS) - which is the heart of the portable
system and provides the foundation for all the higher level functions.
\item Host System Interface (HSI) - the interface between the portable IRAF
system and a particular host system. At the heart of the HSI is the IRAF
\irafname{kernel}, a library of host dependent primitive subroutines that
connects the system independent VOS routines to the host operating system.
Each host system requires a different kernel, hence we speak of the UNIX/IRAF
kernel, VMS/IRAF kernel, and so on.
\end{itemize}
\noindent
All of these interconnected, yet separable, subsystems
act together to form the IRAF data analysis environment. In
most cases the user need not be further concerned with this structure,
except to understand that the specific part of this structure that
this tutorial addresses is the Command Language or CL.
IRAF is designed as an open system that can be extended to add
new analysis capabilities, and that can support user customization
of the existing facilities. There are several levels of customization
available, that range from tailoring task parameters to special needs;
through "re-packaging" existing functions into application specific tasks;
and extending to installation of new compiled code tasks in the
environment. There are a variety of facilities provided in IRAF
to assist the user in the creation and installation of such new tasks.
It is not \emphasize{essential}
that all of these functions be performed in the IRAF way, but full
integration of a user task within the IRAF environment can best be
accomplished by using the facilities that are provided. However,
even without the use of the IRAF interfaces, other tasks may be
incorporated into the user's operating environment and
used as if they were part of the distributed system.
The applications packages and the VOS routines are designed to be
rather stable, and have been coded in the IRAF SPP language for
portability. The kernel layer supports portability across
operating system architectures, and its interface is stable, but
the inner details change as a function of the requirements and
capabilities of the host operating system. The CL is also
rather stable, since it forms the user's interface to the system,
but it is also an area where change is anticipated, as the system evolves
to meet the needs of the users. Because the CL is itself a program
that is supported by the VOS and isolated from the rest of the system
by the VOS, it can be evolved as required without perturbing the other
parts of the system.
\subsection{Function of the Command Language}
\ppind
The basic function of the Command Language is to
provide a clean, consistent interface between the user and the various
packages of functions that complete the IRAF environment.
The CL provides an interface between the user and all applications
programs, giving the user complete control over the parameters, data, and
system resources (graphics devices, etc.) used by IRAF programs.
Many features have been incorporated into the CL to provide
on-line support for users, whether they are old hands or new to the system.
The packages of programs that are provided offer
many of the standard functions for data analysis, and they can
be invoked interactively, one at a time, to perform many common
operations. The execution of these functions is controlled
by various parameters, and users may define their
own values for the parameters as required. IRAF preserves the
last value used, and presents it as the default value upon next
use. Furthermore, there are facilities at several levels to allow
users to assemble existing functions into new tasks that perform
the specific operations on their data sets. This
customization can involve new assemblages of existing functions
or the inclusion of new functions written in the interactive CL
language or in compiled languages.
The CL will primarily be used as a \emphasize{command} language,
but it is also an interpreted \emphasize{programming} language.
To be a good \emphasize{command} language, the CL must make
it as easy as possible to enter commands that perform common functions.
To this end the CL provides command menus, minimum-match name abbreviations,
parameter prompting and parameter defaults, tutoring on command parameters
and options, and a concise syntax for simple commands.
There is also a history mechanism that supports recall of previous commands
and easy error correction within them.
A good interactive \emphasize{programming} language must
be reasonably efficient, be able to evaluate complicated expressions,
to compile and run general procedures, and to offer the user an interpreted
environment for investigating his data and exploring the applicable
range of analysis techniques. This version of the CL (Version 2.3) includes
all of the command language features of the earlier versions and makes
major strides in the direction of becoming a powerful interactive
programming language as well, although much remains to be done before the
CL provides a reasonably complete and efficient interpreted programming
environment.
This may sound complicated at this point, but examples
presented throughout the body of the text will help
clarify the use of the various features. We suggest a first reading of
this introductory section and the next chapter, and then a session at
the terminal, trying out the examples as presented.
\subsection{Capabilities of the CL}
\ppind
Besides fulfilling the basic functions of a command language,
the CL is capable of performing as a programmable desk
calculator, evaluating expressions, executing CL script tasks
or external programs, and doing some rather sophisticated
programming functions. These features provide
a means of connecting tasks to build new high level operators.
The user's interaction with newly created tasks appears the same as
interactions with the standard tasks and utility packages,
as will become apparent in the discussions on usage and script tasks.
The CL has many features familiar to UNIX users in that
I/O redirection, pipes and filters are provided.
The output of any task may be routed to a file (redirection)
or to another task (pipes), and many functions are provided to
perform standard transformations on a variety of data types (filters).
Be aware, however, that there are many differences between the CL
and the UNIX command interpreters.
The CL and the IRAF system present the user with a
complete data analysis environment which is independent of the underlying
operating system. Users running IRAF under UNIX, VMS, AOS, or some
other operating system have the same analysis environment available
to them and can type exactly the same commands while in the CL.
The CL supports an open environment in which packages of application
specific tasks may be created and run. Some of these packages
have been prepared by the developers to provide a variety of utility
services, others that deal with specific instruments and analytic
techniques are being made available,
and still others can be created by you, to support your
own view of the data analysis process. Beyond this, mechanisms exist
that allow compiled external programs to be inserted in the system in
such a way that they appear (and act) as an intrinsic part of IRAF.
It is this open-ended nature that makes IRAF so powerful in its
support of a variety of analysis activities.
\newpage
\section{Getting Started}
\subsection{Setting up the IRAF environment}
\ppind
A visitor wishing to use IRAF does not need to take any special
action to do so.
Computer support personnel will provide an account on one of the analysis
computers and configure the environment as necessary to run IRAF.
Staff members and long term visitors will already have established
themselves with an account and will only need to perform a few simple
operations before the CL and IRAF can be used. \footnote{ {\bf VMS :} The
command {\eighttt IRAF} must be entered to define system symbolic names.
This command can be entered at the terminal or stored in your VMS LOGIN.COM
file; it must be present in the LOGIN.COM file for queued IRAF background
jobs to startup correctly.}
After this has been done, all of the other
commands referenced within this document will be available.
An interactive IRAF session begins with entry of the command
\usertype{cl} to run the CL.
When the CL starts up, it looks for a file called \filename{LOGIN.CL} in the
user's current directory. If this directory does not contain a
\filename{LOGIN.CL} file, the CL will function for simple things
such as the evaluation of numerical expressions, but will not work
properly for all functions. Therefore, you should always run the CL
from a properly configured IRAF login directory.
This directory needs to be initialized for IRAF before the
CL is invoked; you can use the \usertype{mkiraf} command to setup the
IRAF environment. The login directory, once set up, can be used for any number
of sessions, and if you wish, you can set up several independent login
directories and data directories for working with different types of data.
\noindent
Summarizing the steps required to set up the IRAF environment:
\begin{enumerate}
\item Decide on a login directory.
\item Go there.
\item Type \usertype{mkiraf}.
\end{enumerate}
\noindent
That is all that is required. The \usertype{mkiraf} command performs
several actions, the most important of which are making a
\filename{LOGIN.CL} file which you may wish to edit to change defaults,
and the creation of a \filename{UPARM} subdirectory, which is used
by IRAF to store your customized parameter sets.
The default login file consists mostly of environment declarations
(\usertype{set} statements) that define directories, devices, and so on.
The function of the environment and the significance of the
standard \irafname{environment variables} are discussed in \S 4.2.
The \usertype{mkiraf} command can be entered at any time to reinitialize
the environment, i.e., create a new \filename{LOGIN.CL} from the system
default and clear the \filename{UPARM} directory. This is recommended
periodically to pick up any recent changes in the system, and may be
required when a major new release of the system is installed.
\subsection{Starting the CL}
\ppind
After configuring your IRAF directory, type the command \usertype{cl}
to start the command language. After a bit the welcome message
will appear on your terminal, and the first or root ``menu'' of IRAF will
be displayed. This menu gives the names of the packages available through
the CL. The \comptype{cl>} prompt will be issued indicating that the
CL is ready to accept commands.
\begin{quotation}
\begin{center}
\comptype{Welcome to the IRAF.}\\
\smallskip
\end{center}
\begin{verbatim}
dataio images lists noao sdas system
dbms language local plot softools utilities
\end{verbatim}
\comptype{cl>}
\end{quotation}
Everything shown in the root menu of IRAF is a \irafname{package} name.
A package is a set of \irafname{tasks} that are logically connected.
For example, the \taskname{plot} package contains an assortment of
general plotting tasks. You must \emphasize{load} a package before any of the
tasks therein can be run; you can load any package by simply typing its name.
\begin{quotation}\noindent
\comptype{cl>} \usertype{plot}
\end{quotation}
\noindent
would load the plot package and make the tasks in the package known to the CL.
To unload the current package type \taskname{bye}; this frees any system
resources used by the loaded package and restores the CL to state it was in
before the package was loaded.
Note that the system comes up with the \taskname{clpackage, system, language}
and the default \taskname{user} packages already loaded (the \taskname{user}
package allows the user to personalize the system, and is discussed in \S 5.6).
A comment should be made at this point about case sensitivity in IRAF.
The CL accepts input in both upper
and lower case, and distinguishes between them, i.e. a \usertype{'Y'} is
different from a \usertype{'y'}. All command names are purposely
specified in lower case, which is the default, and all user responses
are expected to be in lower case as well. Upper case or mixed case
names and commands are possible, but should be used with care.
Once the \comptype{cl>} prompt appears, many tasks will be available and
ready for execution. A list of all loaded packages and the tasks in each
package may be obtained by typing two question marks (\usertype{??}).
This will list the tasks organized by package, starting with the current
package. The packages are listed in the
order in which they are searched when you type a command. Type one question
mark (\usertype{?}) to list only the task names in the current package,
or \usertype{?{\it packagename}} to list the tasks in
package ``packagename''.
\subsection{Executing commands from the CL}
\ppind
At this point you may want to try executing a few simple commands.
First try the \usertype{help} command. This will give additional
information about the tasks in the current package.
\begin{quotation}\noindent
\comptype{cl>} \usertype{help}
\end{quotation}
For detailed information about a particular package or task, type
\usertype{help} followed by the name of the package or task for which help
documentation is desired. For example,
\begin{quotation}\noindent
\comptype{cl>} \usertype{help system}
\end{quotation}
\noindent
will print detailed information about the \taskname{system} package, and
\begin{quotation}\noindent
\comptype{cl>} \usertype{help page}
\end{quotation}
\noindent
will print detailed information about the \taskname{page} task which is
in the \taskname{system} package (after each page of text, the \taskname{help}
program will prompt with a list of keystrokes and pause until you type one
of them).
Now let's try running some tasks from the \taskname{system} package, which
is already loaded. To display the file \filename{LOGIN.CL} on the terminal,
enter the following command:
\begin{quotation}\noindent
\comptype{cl>} \usertype{page login.cl}
\end{quotation}
The \taskname{page} routine, like \taskname{help}, will pause at the end of
each page of text, waiting for you to type a command keystroke, e.g.,
to display the next page of text, quit, return to the start of the file,
go on to the next file if paging a set of files, and so on (typing \key{?}
in response to the \taskname{page} prompt will cause a summary of the
acceptable keystrokes to be printed). To get a directory listing of the
files in the current directory, type:
\begin{quotation}\noindent
\comptype{cl>} \usertype{dir}
\end{quotation}
\noindent
Observe that all package, task, and parameter names may be abbreviated
while working interactively. Any abbreviation may be given which contains
sufficient characters to identify the name unambiguously; if the
abbreviation is not unique, an error message is displayed. In general
the first two or three characters are enough to identify most commands,
but changes to the operating environment, i.e. loading additional packages,
may require entering more characters or specifying the
\emphasize{packagename}
as a prefix to unambiguously identify the required command.
To list all your files with the \filename{.CL} extension, you can type:
\begin{quotation}\noindent
\comptype{cl>} \usertype{dir $*$.cl}
\end{quotation}
As you gain familiarity with the CL you may find that you
cannot remember the IRAF command to do something, but do know the
correct command to use in the native operating system. There is an
\emphasize{escape} mechanism built into IRAF, in that any operating system
specific command may be used by prefixing it with a~\usertype{`!'}.
There are some cautions to be observed that are described in detail
(\S 4.1), but this knowledge may remove one possible source of frustration.
Of course, the CL commands \usertype{`?'} or \usertype{`??'} may also be used
to produce a display of the available package names and functions.
Packages are loaded the same way tasks are run, viz. merely by typing the name
of the package as a command (a package is in fact a special kind of task).
If the desired package is a subpackage of a package, the main package must
be loaded first. For example, suppose we want to run the \taskname{precess}
task. To find out what package \taskname{precess} is in we run \taskname{help}
on the task \taskname{precess} and observe that the package path (printed at
the top of the help screen) is "noao.astutil". This means that the
\taskname{precess} task is in the \taskname{astutil} package which is in the
\taskname{noao} package, which we recognize as a root level package.
We load first the \taskname{noao} package and then the \taskname{astutil}
package by typing:
\begin{quotation}\noindent
\comptype{cl>} \usertype{noao} \\
\comptype{no>} \usertype{astutil} \\
\comptype{as>}
\end{quotation}
\noindent
The set of new tasknames now available to you will be displayed automatically.
Note that the prompt will change from \comptype{cl>} to \comptype{no>}
to \comptype{as>} to let you know you have entered another package.
One of the astronomical utility programs available is the \taskname{precess}
program, which is used to precess lists of astronomical coordinates.
The simplest way to run \taskname{precess} is to type only its name:
\begin{quotation}\noindent
\comptype{as>} \usertype{precess}
\end{quotation}
\noindent
The CL will then prompt you for the parameters it requires to run the program;
in this case, the CL needs the name of an input file containing a list
of coordinates to be precessed and the years over which the
precession is to be computed. If you do not have the coordinates in a
file, give the filename as \filename{STDIN} (it must be upper case), and
you can then enter the coordinates interactively from the terminal.
Any number of coordinates (input lines from the special file \filename{STDIN})
may be entered; signal the ``end of file'' for \filename{STDIN} by typing
the EOF key, e.g., \key{CTRL/Z}.
\footnote {\key{CTRL/Z} is the standard EOF (end of file)
sequence on VMS and most UNIX systems. Similarly, \key{CTRL/C} is the
standard interrupt key on these systems. For simplicity we use the explicit
control codes to refer to these functions in most of the IRAF documentation,
but the reader should be aware that different control sequences may be used
on the local system and be prepared to make the translations. For example,
the key \key{CTRL/D} is often used to signal EOF instead of \key{CTRL/Z}.}
Coordinates are entered in pairs (RA and DEC, delimited by spaces) in either
decimal or sexagesimal notation (e.g., 12.5 or 12:30:04.2). If you have any
problems type \usertype{help precess} for additional information, including
examples.
If you have a long list of coordinates to precess, try entering
them into a file. The command:
\begin{quotation}\noindent
\comptype{as>} \usertype{edit coord1950.txt}
\end{quotation}
\noindent
will call up the default editor (Vi on UNIX systems; EDT or EMACS on VMS
systems) to edit the file \filename{COORD1950.TXT}.
After creating your coordinate file and exiting the editor in the usual
fashion, you will be back in the CL. Now try executing the \taskname{precess}
program, using the file \filename{COORD1950.TXT} as input:
\begin{quotation}\noindent
\comptype{as>} \usertype{precess coord1950.txt}
\end{quotation}
\noindent
Of course, the output will still appear on the terminal, and
you may wish to \irafname{redirect} the output into a file as well:
\begin{quotation}\noindent
\comptype{as>} \usertype{precess coord1950.txt $>$ coord1984.txt}
\end{quotation}
If the coordinate list is \emphasize{very} long, you may wish to process
the list as a background job. To avoid interruptions from parameter
prompts by the background task (it will inquire at the terminal), be sure to
enter all the necessary parameters on the command line.
To execute the task \taskname{precess} in the background, type:
\begin{quotation}\noindent
\comptype{as>} \usertype{precess coord1950.txt 1950 1984 $>$ coord1984.txt \& }
\end{quotation}
\noindent
The final `\usertype{\&}' tells the CL to run the task in the background.
The two parameters 1950 and 1984 will be passed to the task; you will
not be prompted for them.
Once the background task is started, the CL will be available for
further interactive use and you will be
informed when the background job is complete. The use of background
tasks for batch processing is treated in more detail in \S 5.4.
\subsection{A Comment on Input and Output}
\ppind
The notion of output \irafname{redirection} has already been introduced, and the
topics of input redirection (accepting input from a file rather than
the terminal) and \irafname{pipes} (connecting the output from one task to the
input of the next) will be dealt with in \S 3.3. The point to be
made at this time is that \emphasize{all} tasks can be thought of as having
three main I/O paths associated with them:
\begin{quotation}\noindent
\begin{tabular}{l l}
\filename{STDIN} & the input path \\
\filename{STDOUT} & the output path \\
\filename{STDERR} & where error messages appear
\end{tabular}
\end{quotation}
%\begin{quotation}\noindent
%\begin{description}
%\item[\filename{STDIN}] the input path
%\item[\filename{STDOUT}] the output path
%\item[\filename{STDERR}] where error messages appear
%\end{description}
%\end{quotation}
\noindent
By default, all of these I/O paths are connected to your terminal
(referred to as \filename{TTY}) and you may redirect any one or all
of them using simple command line requests. The output
\emphasize{redirection} introduced in the previous example of
\taskname{precess} is an example of just such an action. Other
examples in \S 3.3 will cover this topic in more detail.
There are other standard output streams as well that depend on the
specifics of the task. Not surprisingly, graphics tasks
want to talk to a graphics terminal or other suitable device
(\filename{STDGRAPH}) and image tasks need access to an image display
(\filename{STDIMAGE}). There is a stream for the graphics plotter device as well
(\filename{STDPLOT}). Each of these \emphasize{logical} devices is assigned
to a physical device, either by commands in your \filename{LOGIN.CL} file
or by explicit parameters in the function calls.
\subsection{The Graceful Exit}
\ppind
Now that you are a couple of layers deep into the CL, you may wonder
how to get back out again. If you type \usertype{bye}, you will exit the current
package and return one level of loaded packages. You cannot, however, type
\usertype{bye} at the root CL level (\comptype{cl>} prompt).
The command:
\begin{quotation}\noindent
\comptype{cl>} \usertype{logout}
\end{quotation}
\noindent
may be used to exit directly from the CL at any level.
The \usertype{bye} command or the \key{CTRL/Z} sequence that signals
EOF will exit from any task except the CL itself. This is to
prevent an unintended \emphasize{logout} from occuring if a series
of EOF's are entered from the terminal.
For a less gentle departure from function execution, the interrupt
sequence \key{CTRL/C} may be used at any level.
This will usually terminate any task that appears to
be hung or is operating in error, but will normally put you
back in the CL in interactive mode.
\newpage
\section{Basic Usage}
\ppind
The CL can be used as both a command language and a programming language,
but most first-time users (and many experienced ones) will mostly
use the command features of the language. Commands to the CL may be
entered at the terminal, one at a time, or they may be read in from
a script file; in either case the syntax is the same and abbreviation
of command names and variable names is supported. When the CL is
being used for programming the rules are more restrictive, and
full name specification is required, as is a more formal specification
of task parameters. During the early sections of this document
only the command forms will be used for simplicity.
Parameters to a task may be specified on the command line for brevity,
and prompting is automatically enabled for any required parameters that
are not specified or that are given values that are out of range.
\subsection{Command Syntax}
\ppind
The form of a command that calls an IRAF task is the
\emphasize{task name}, optionally followed by an
\emphasize{argument list}. The argument
list consists of a list of \emphasize{expressions} delimited by spaces.
Simple filenames or string arguments that appear in the unparenthesized
argument list need not be quoted, but any string that contains an
embedded blank or other special characters should be quoted.
\emphasize{Positional} arguments (typically the first few
arguments \emphasize{required} for a function must be given first and
in order.
All of these may be followed by \emphasize{param = value} keyword assignments,
\emphasize{param$\pm$} switches, and \emphasize{file} I/O redirection
assignments. These last three types of arguments may appear in any order.
In general, the form is as follows :
\begin{quotation}\noindent
\begin{tabular}{lll}
\comptype{cl>} {\it taskname} [{\it expression} $\ldots$ ] &
[{\it param=value}] & [$<${\it filename}] \\
& [{\it param}$\pm$] & [$>${\it filename}] \\
& & [$>>${\it filename}] \\
& & [$>\&${\it filename}]
\end{tabular}
\end{quotation}
\noindent
Any or all of these types of parameters may be present
and defaults are provided for most parameters.
In particular, the only parameters that
\emphasize{must} be set are the \irafname{required parameters}
and if these are not specified on the command line, the CL will prompt
for them. Other parameters and switch values are defaulted, but may be
overridden if desired.
The I/O streams typically default to the login terminal, but the
redirection operators may be used to request: input from a file
(\usertype{$<$}); output to a file(\usertype{$>$}); appending to
a file (\usertype{$>>$}); or redirecting the standard output and the
standard error stream to a file (\usertype{$>$\&}).
The form of a command line need not be limited to a solitary call to a task.
Several tasks may be called in sequence on a single command
line, using the semicolon character `;' to delimit each call:
\begin{quotation}\noindent
\comptype{cl>} \usertype{clear; dir}
\end{quotation}
\newpage
\noindent
If the command sequence is too long to fit on a single line, it can be
enclosed in braces:
\begin{quotation}\noindent
\comptype{cl>} \usertype{\{ } \\
\comptype{>>>} \usertype{clear} \\
\comptype{>>>} \usertype{directory} \\
\comptype{>>>} \usertype{beep} \\
\comptype{>>>} \usertype{\} }
\end{quotation}
\noindent
Note that the prompt changes to \comptype{>>>} after the first
line to signal that the CL requires more input before it will execute the
task. (In this particular example, the CL is waiting for a `\}'.)
Such a construct is called a \irafname{compound statement} and may be
used to aggregate several simple commands into a single new command.
Compound statements may be used directly from the terminal (or within
scripts as we shall see later) and will be treated as a single
entity by the display and editing commands.
An arbitrary number of commands may be entered in a compound statement
and then executed as a single unit.
Commands may be strung together in another way too, by use of the
pipe notation, which requests that the output of one command
be used as the input to the next. Creation of the temporary files that
support this, and connection of the task logical I/O paths to these
files is handled automatically by IRAF.
\begin{quotation}\noindent
\comptype{cl>} \usertype{type coord1950.txt \pipe precess 1950 1984}
\end{quotation}
\noindent
The pipe symbol `{\tt |}' directs the CL to feed the output of
one task (\usertype{type}) to the input of the next (\usertype{precess}).
\noindent
If an argument list is too long to fit on one line,
continuation is understood if the last item on a line is a backslash
`$\backslash$', the pipe symbol, or an operator (e.g., `$+$' or `{\tt //}').
\begin{quotation}\noindent
\comptype{pl>} \usertype{graph "pix[*,5],pix[*,10],pix[*,15]" po$+$
marker=circle \bsl } \\
\comptype{>>>} \usertype{xlabel=column ylabel=intensity \bsl } \\
\comptype{>>>} \usertype{title = "lines 5, 10, and 15"}
\end{quotation}
Quotes \emphasize{may} be used around
any string of characters, but are generally not required on commands
entered at the terminal. In the previous example quotes are used
around the string value of the \usertype{title} parameter because the
string contains embedded spaces.
To make precise the rules for quoted strings:
a string need not be
quoted provided [1] it appears as an identifier (a name) in an argument
list \emphasize{not} enclosed in parentheses, AND [2] the string does not
contain any blanks or other characters which are special to the CL,
e.g., the i/o redirection symbols, the pipe symbol, semicolon, the begin
comment character (\usertype{\#}) or curly braces.
If the string contains any special characters it must be quoted.
Comments may be freely embedded in a command sequence.
Everything following the comment character on a line is ignored by the parser,
so entire comment lines may be entered by starting the line with a comment:
\begin{quotation}\noindent
\comptype{cl>} \usertype{\# This is a full line comment} \\
\comptype{cl>} \usertype{type login.cl \hfill \#~Display~the~login~file }
\end{quotation}
\noindent
or by appending a comment to the end of a line as in the last example.
\subsection{Task Parameters}
\ppind
Nearly all tasks have a formally defined set of parameters associated
with them. The parameters for a task may be listed with the command
\usertype{lparam }{\it taskname}. For example, to list the parameters for
the task \taskname{delete}, type:
\begin{quotation}\noindent
\comptype{cl>} \usertype{lparam delete}
\end{quotation}
\noindent
The \usertype{lparam} command produces a display of the parameters of the
named task in the order in
which they must be given on the command line; it shows the current values
of the parameters and the prompt strings as well.
After one types \usertype{lparam delete}, the following list will appear,
giving the parameter name, its
current value, and the prompt string associated with it:
\begin{verbatim}
files = list of files to be deleted
go_ahead = yes delete or not ?
(verify = no) verify operation before deleting each file ?
(default_action = yes) default delete action for verify query
(allversions = yes) delete all versions of a file ?
(subfiles = yes) delete any subfiles of a file ?
(mode = ql)
\end{verbatim}
Notice that there are two types of parameters, those with
parentheses around the \emphasize{param = value} fields and those without.
The parameters not enclosed in parentheses are called
\irafname{positional parameters}; they are required parameters
and will be queried for if not given on the command line. Positional
\emphasize{arguments} are the first arguments on the command line (following
the command itself), and they are associated with parameters by their position
on the command line. The first positional parameter will be set by the first
positional argument on the command line, the second positional parameter by
the second positional argument, and so on.
The parameters enclosed in
parentheses are called \irafname{hidden parameters}, and are the topic of
the next section. Either type of parameter may be referred to by a
\usertype{param = value} clause, although these parameter references
must \emphasize{follow} the positional arguments. Such name references
\emphasize{must} be used for the hidden parameters, but may be used for all.
Some of the parameter handling actions in the CL are rather elaborate
and require discussion. As was just noted, the CL will automatically
prompt for any required parameters that have not been provided in some
way by the user. Beyond this, the normal action of the CL is to
remember the parameters that you last used, and when that parameter
name is next encountered, to offer the last value used as the new
default value. This \irafname{learning} of parameters is intended
to reduce user effort and is a means of customizing use of the system.
The learned parameters are saved for you in the \filename{UPARM}
subdirectory, and will be preserved across uses of the system.
\subsubsection{Hidden Parameters}
\ppind
The parameters of the \usertype{delete} task that appeared in
parentheses are \taskname{hidden parameters} for the task.
The CL does not query for hidden parameters, but automatically
uses the default values. However, a query will be generated for
even a hidden parameter if there is no
default value or if the default value is illegal for some reason.
Hidden parameters may be set on the command line, but unlike positional
parameters, the value from the command line will not be learned, i.e., it will
not become the new default value. The default value of a hidden parameter may
be changed only by an explicit assignment, or by use of the \taskname{eparam}
task (\S 3.2.3), and you should exercise caution in doing this,
because it is easy to forget that hidden parameters have been changed.
Hidden parameters are often used to change the behavior of a task,
achieving considerable flexibility without requiring many arguments on the
command line, and without annoying queries for parameters. Hidden parameters
make it possible to support functions like \taskname{graph} that
support different display options, since users can modify
the default behavior of the task to make it behave in the manner they want.
Hidden parameters can also be dangerous if they are used improperly
(e.g., for data dependent parameters in scientific programs).
The \taskname{delete} task is a good example of a task that is useful to
personalize. The default behavior of \taskname{delete} is simply to delete
the named file or files (provided they are not protected in some way).
File deletion can be hazardous, of course, particularly since a pattern
matching template may be used to delete many files. As many of us are unhappily
aware, inadvertently typing
\begin{quotation}\noindent
\comptype{cl>} \usertype{delete $*$}
\end{quotation}
\noindent
will bring about the swift deletion of \emphasize{all} of the (unprotected)
files in the current default directory.
As IRAF recognizes a number of special pattern matching metacharacters in
addition to `$*$', one could easily free up a lot of disk space if one were
not familiar with the use of pattern matching templates.
To reduce the possibility of such devastating side-effects, you might wish to
change the default behavior of \taskname{delete} to verify each file deletion.
This is done by changing the value of the hidden parameter \taskname{verify},
which defaults to \emphasize{no}. Hidden parameters that are boolean flags
(yes/no) may be overridden temporarily on the command line as follows:
\begin{quotation}\noindent
\comptype{cl>} \usertype{delete $*$.dat verify=yes}
\end{quotation}
\noindent
or, equivalently,
\begin{quotation}\noindent
\comptype{cl>} \usertype{delete $*$.dat verify$+$}
\end{quotation}
\noindent
Either of these commands would cause a prompt to be issued naming
each file matching the template and asking if you want to delete
it (this would happen even if the task were running in batch mode).
If you set a hidden parameter on the command line, you override the value
of that parameter only for that command; the default value is not changed.
As indicated before, to change the default value of a hidden parameter,
an explicit assignment is required:
\begin{quotation}\noindent
\comptype{cl>} \usertype{delete.verify = yes}
\end{quotation}
\noindent
which will cause all subsequent file deletions to be verified, unless the
\usertype{delete} command is issued with the argument \usertype{verify=no}
or \usertype{verify$-$} on the command line. The change may be undone by
another assignment, or by \emphasize{unlearning} the task parameters.
\subsubsection{Learning and Unlearning parameters}
\ppind
The CL facility called \irafname{learn mode} is designed
to simplify the use of the system.
By default, the CL automatically ``learns'' the value of all task
\irafname{parameters} that are prompted for or explicitly set. In practice,
this means that once a required parameter (such as the precession epoch in
the \taskname{precess} example)
has been set, it need not be respecified. The CL will still prompt for
required parameters, but the default value displayed will be the
last value you entered. Simply hitting \key{RETURN} will cause the CL
to reuse the old value; but a new value may be entered and it will
be preserved as the new default. If the required parameters are
specified on the command line, you will not be prompted for them, and the
value you specify will still be learned.
The parameter-learning mechanism has other ramifications as well.
The most recently used parameter values are automatically preserved
by the CL in \filename{.PAR} files stored in your \filename{UPARM} directory.
These saved parameter
sets are reloaded when you next start the CL, thus providing a
\emphasize{memory} of the options that you used in a previous session.
Any command line arguments
that you specify will override these \emphasize{learned} defaults, but they
will be available if you wish to use them.
An explicit command may be used to
\emphasize{reset} the values of parameters,
i.e., to restore the defaults. The \usertype{unlearn} command restores the
system default values of all of the parameters for a single task or for an
entire package.
\begin{quotation}\noindent
\comptype{cl>} \usertype{unlearn delete}
\end{quotation}
\noindent
will restore the parameters of the task \taskname{delete} to their default
values, and
\begin{quotation}\noindent
\comptype{cl>} \usertype{unlearn system}
\end{quotation}
\noindent
will restore the defaults for \emphasize{all} of the tasks in the system
package. If you want to restore the defaults for all the parameters in your
IRAF environment, delete the \filename{.PAR} files from the logical directory
\filename{UPARM} :
\begin{quotation}\noindent
\comptype{cl>} \usertype{delete uparm\$$*$.par}
\end{quotation}
\subsubsection{Specifying Parameters to a Task}
\ppind
The simplest and fastest way to invoke a task is to simply type in the name
of the task followed by the necessary arguments on the command line, as we
have been doing in most of the examples thus far.
In many cases, the arguments for a task will be obvious, either from the context
and the prompts issued by the task, or from the \usertype{lparam} display.
If you are unsure about how to proceed,
you can simply type the task name, and answer the questions.
Each prompt may include minimum and maximum acceptable values,
if such apply, and the current value of the parameter if such exists.
For parameters that have only a fixed set of allowable values the list of
valid options will be enumerated.
Alternatively, the \usertype{eparam} command may be used to invoke the
parameter \emphasize{editor}. The \taskname{eparam} task presents the
parameters of a task in a tabular display on the screen and supports the
use of the cursor keys to navigate the options. It also has commands for
changing entries, or for recalling previous entries for further editing.
The command:
\begin{quotation}\noindent
\comptype{cl>} \usertype{eparam precess}
\end{quotation}
\noindent
will display the parameters for \taskname{precess} (the \taskname{noao} and
\taskname{astutil} packages must first be loaded). The \key{RETURN}
key will move you down the list or the cursor keys
may be used to move among the parameters, and any entries that you
type will replace the displayed values. You may exit from
\taskname{eparam} at any time with a \key{CTRL/Z} and the parameters
for the task will be updated with your newly edited values.
If you wish to exit the editor \emphasize{without} updating the
parameters, use the interrupt request \key{CTRL/C} instead.
Specifying parameters via \usertype{eparam} has the same effect as
does entering them on the command line, they will be remembered by IRAF
and not prompted for when the function is next invoked.
\usertype{Eparam} and the history editor \usertype{ehistory} both
use the same simple set of editor commands, and they can mimic several
editors that are common on the currently supported systems. For any
of these editors the default style supports use of the cursor (arrow keys)
on the terminal and the use of the \key{DELETE} key. The sections on
editors (\S 5.2-3) describe this in more detail.
If you find that you must invariably run \taskname{eparam} before running
a particular task, e.g., because the task has too many parameters to be
specified on the command line, it is possible to get the CL to run
\taskname{eparam} for you automatically whenever the task is run interactively.
This is called \usertype{menu mode}. To set menu mode for a task we
set the string value of the \taskname{mode} parameter of the task; all
tasks have such a parameter. For example,
\begin{quotation}\noindent
\comptype{cl>} \usertype{precess.mode = ``ml''}
\end{quotation}
\noindent
will set both menu and learn mode for the task \taskname{precess}.
The default mode for most tasks is \usertype{ql}, i.e., query (the task
will query for all parameters not set on the command line) plus learn
(old parameter values are learned).
Once you are familiar with the operation of a task, you can
enter the parameter values on the command line in the
order in which they appear in the \usertype{lparam} listing.
Parameters may also be set using the \usertype{param = value} clause on the
command line, but remember that any positional arguments must be given first.
Note that a command line argument may be any general expression, much like
the arguments to a Fortran subroutine.
\begin{quotation} \noindent
\comptype{cl>} \usertype{precess stdepoch= (1984$+$i$*$4)}
\end{quotation}
\noindent
Here an expression is used to compute the value of the
hidden parameter \taskname{stdepoch}. Note that the expression must
be enclosed in parentheses in order to cause it to evaluated, since it
will otherwise be treated like a string and just passed into the task
for it to handle. The variable \usertype{i} must previously have
been set to some legal value; otherwise the CL will prompt for it.
\subsection{Pipes and I/O Redirection}
\ppind
We have already seen how tasks can take their input from either the
terminal or from a file, and send the output to either the terminal
or a file. By default, both the standard input and standard output for a
task are written to the user terminal; the capability to change them
on the command line is called \emphasize{I/O redirection}. The Appendix of
IRAF commands at the end of this document was created with the
following simple command:
\begin{quotation}\noindent
\comptype{cl>} \usertype{help {\it pkg} $>$ {\it pkg.txt} }
\end{quotation}
\noindent
where the name of each package was substituted for {\it pkg}.
The pipe syntax is a powerful kind of I/O redirection. A pipe is formed by
connecting the output of one task to the input of another task; an arbitrary
number of tasks may be connected together in this way to form a single command.
UNIX users will already be familiar with the concept and uses of pipes,
but be aware that CL pipes differ from UNIX pipes in that the CL tasks
execute \emphasize{serially} rather than concurrently (i.e., nothing comes out
of the end of the pipe until \emphasize{all} the input has been processed).
Another difference between IRAF and the usual UNIX implementation
is that IRAF pipes are implemented with temporary files which are
managed by the system.
Note also that queries for parameters are not affected by the use of
I/O redirection or pipes, i.e., required parameters will still be
prompted for when requested by a task.
A simple example of the use of a pipe is redirecting the output of a command
to the line printer. This can be done with I/O redirection as follows:
\begin{quotation}\noindent
\comptype{cl>} \usertype{help plot $>$ temp} \\
\comptype{cl>} \usertype{lprint temp} \\
\comptype{cl>} \usertype{delete temp}
\end{quotation}
\noindent
The pipe notation accomplishes the same thing and is more concise:
\begin{quotation}\noindent
\comptype{cl>} \usertype{help plot \pipe lprint}
\end{quotation}
\noindent
For a more sophisticated example of the use of pipes, load the
\usertype{lists} package and try out the following command:
\begin{quotation}\noindent
\comptype{cl>} \usertype{?? \pipe words \pipe match : stop$+$ \pipe
sort \pipe table}
\end{quotation}
\noindent
This sequence of commands takes the list of menus produced by \usertype{??},
breaks it into a list of words, filters out the lines that contain the colon
character (the package names), sorts the list, and prints a menu listing the
tasks in all loaded packages.
The following example shows the use of a pipe-filter to sort the output
of a long form directory listing of the system library directory \filename{LIB},
sorting the list in reverse numeric order by the size of the file, so that
the largest files come out at the top of the list:
\begin{quotation}\noindent
\comptype{cl>} \usertype{dir lib l$+$ \pipe sort num$+$ rev$+$ col$=$3}
\end{quotation}
\noindent
We can go a bit further and extend the pipe to print only the ten largest
files and page the output:
\begin{quotation}\noindent
\comptype{cl>} \usertype{dir lib l$+$ \pipe sort num$+$ rev$+$ col$=$3 \pipe
head nlines$=$10 \pipe page}
\end{quotation}
Any or all of the input, output or error logical I/O streams may be
redirected with simple command line requests. The next example shows
the use of redirected input and output streams:
\begin{quotation}\noindent
\comptype{cl>} \usertype {
match \upa\usertype{set} $<$ home\$login.cl $>$ names.env }
\end{quotation}
\noindent
This command reads from your \filename{LOGIN.CL} file, created by the
initial \usertype{mkiraf} command, matches all the lines that contain
\usertype{set} environment statements (the metacharacter \upa (up-arrow)
causes \usertype{set} to be matched only at the beginning of a line),
and writes these out into the file \filename{NAMES.ENV}.
The \usertype{$>$} redirection operators will create a new output file.
To append to an existing file we use the \usertype{$>>$} operator instead:
\begin{quotation}\noindent
\comptype{cl>} \usertype{set \pipe match tty $>>$ names.env}
\end{quotation}
\noindent
which will scan for all the environment variables having something to do with
the terminal and append them to the file \filename{NAMES.ENV}.
The operators \usertype{$>$} and \usertype{$>>$} will redirect only the
standard output stream \filename{STDOUT}; error messages will still come
out on the terminal. To redirect both \filename{STDOUT} and \filename{STDERR}
the operators \usertype{$>$\&} and \usertype{$>>$\&} should be used instead.
The graphics output streams may be redirected (but not piped) much as is
done for the ordinary textual output streams.\footnote{This holds only for
standard IRAF tasks, i.e., tasks which use the IRAF graphics subsystem.
This feature is not currently available for the STScI SDAS tasks since they
do not use the IRAF graphics facilities.} For example, to redirect the
standard graphics output of the \taskname{surface} task (in the \taskname{plot}
package) to produce a graphics metacode file \filename{SURF.MC}:
\begin{quotation}\noindent
\comptype{cl>} \usertype{ surface dev\$pix $>$G surf.mc}
\end{quotation}
To redirect the \filename{STDIMAGE} stream, substitute the operator
\usertype{$>$I}, and to redirect the \filename{STDPLOT} stream, use the
operator \usertype{$>$P}. The characters \usertype{GIP} must be uppercase.
The \usertype{$>$} may be doubled to append to an existing file, as for
the standard text streams. As a special case, a graphics stream (or indeed
any stream) may be redirected to the so-called \emphasize{null} file
\filename{DEV\$NULL} to discard the output. For example,
\begin{quotation}\noindent
\comptype{cl>} \usertype {prow dev\$pix 100 $>$G dev\$null}
\end{quotation}
\noindent
will plot row 100 of image \filename{DEV\$PIX}, redirecting the graphics output
into the null file. The null file can be used anywhere a normal file can be
used.
\newpage
\section{Operating System Interface}
\ppind
Although IRAF provides a quite complete environment for data analysis
activities, it must be hosted in some particular operating system whenever
it is being used. The isolation from the peculiarities of any
specific operating system command syntax is rather complete, but there
are instances where the syntax of the underlying system must be
used (host filenames) or where the user may desire to use familiar
commands from the host system. IRAF does allow commands to be passed
through to the host operating system, but because IRAF maintains all of
its own environment descriptors, directory structures, and task and
program information, the operating system commands should only be used
to bring information into the IRAF environment, but not to modify it.
In order to change any of the status or control information that
affect IRAF execution, the commands provided by IRAF must be used.
\subsection{Sending Commands to the Host Operating System}
\ppind
IRAF allows access to the underlying operating system, and hence to
other programs that operate within the native operating system
environment. There are limitations on some of the system facilities that
can be used without regard to side-effects, but, in general, almost any
program can be called from within IRAF.
External programs can be accessed from within the user's environment and will
operate with a standard interface that is compatible with the
rest of the processing functions that are available.
Any command may be sent to the host operating system by prefixing
the command with the escape character `\usertype{!}'. The rest of the
command line will be passed on unmodified. For example, to read your mail
on a UNIX or VMS system:
\begin{quotation}\noindent
\comptype{cl>} \usertype{!mail}
\end{quotation}
\noindent
Upon exiting the mail routine, you will be back in the CL. Almost any
task that is executable in the normal host environment can be invoked
from within IRAF by means of this escape mechanism. The OS escape
is used to implement some of the standard IRAF commands that request
operating system information, such as \usertype{spy}.
The \usertype{edit} command also uses the escape mechanism, so that
the host supported editors can be used, rather than require that a
completely new editor be learned in order to use IRAF.
Occasional conflicts will arise if these external tasks re-assign
their terminal input and output streams or perform other unnatural acts.
If strange things happen when trying to use such tasks from within
the CL, consult your \irafname{IRAF Guru}. The other major source of problems
with host system tasks is that they may depend upon system specific
data that have been defined for the OS but are unknown to IRAF. This
is a particular problem under VMS, which does not pass system environment
parameters to sub-tasks, as does UNIX. Variables that affect the
execution of tasks within the environment are controlled by IRAF and
are passed between the executing tasks, as in described next.
\subsection{Environment Variables}
\ppind
The CL maintains a table of environment variables which
affect the operation of \emphasize{all} IRAF programs.
The environment variables are used to define logical names for directories,
to associate logical device names with a specific physical device,
and to provide control over the low level functioning of the
IRAF file I/O system.
The default environment is created by IRAF at login time, i.e., when the
CL is first run. Part of this initialization uses a standard system-wide,
site dependent file named \filename{HLIB\$ZZSETENV.DEF}. Additional
initialization of personal environment variables, or redefinition
of standard environment variables, may be done with commands
in your \filename{LOGIN.CL} file.
One may add new environment variables, or redefine old ones, at any time during
a session with the \usertype{set} command. \usertype{Set} declarations made
during CL execution, however, may be lost upon exit from a package. To secure
environment declarations for a full session, make them \emphasize{immediately}
after logging in. To make environment declarations permanent, place the
relevant \usertype{set} commands in your \filename{LOGIN.CL} file.
The \usertype{set} command is usually used to change the \emphasize{session}
defaults for output devices and such, but all IRAF programs which write to the
line printer or to a graphics device also permit the device to be selected on
the command line. For example,
\begin{quotation}\noindent
\comptype{cl>} \usertype{set terminal = vt100}
\end{quotation}
\noindent
informs IRAF that the user is using a VT100-type terminal for this session.
When typed without any arguments, e.g.:
\begin{quotation}\noindent
\comptype{cl>} \usertype{set \pipe page}
\end{quotation}
\noindent
\taskname{set} displays a list of the current values of all of the environment
variables. Note that abbreviations are \emphasize{not} supported for
environment variable names, they must be spelled out in full.
If a shorter name is used the CL will silently create a new environment
variable for you, which may not be what you desired at all.
Identifying the kind of terminal you are using, the size of the display
window to be used, and setting other terminal options may most conveniently
be done with the \usertype{stty} command:
\begin{quotation}\noindent
\comptype{cl>} \usertype{stty tek4014 baud$=$1200}
\end{quotation}
\noindent
This command should be used early in the session (if not already present in
the \filename{LOGIN.CL} file) to identify the kind of terminal that you are
using, since the operation of the various editors and of other functions will
be affected by these values. It is only necessary to set baud rate as in
the example if you are working remotely via modem. As was the case with
the \usertype{set} command, typing \usertype{stty} with no arguments will
display the current terminal type and settings.
The current value of \emphasize{individual} environment variables may be
displayed with the \usertype{show} command:
\begin{quotation}\noindent
\comptype{cl>} \usertype{show printer}
\end{quotation}
\noindent
A selection of the more important environment variables is shown in the
following table.
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
\multicolumn{3}{|c|}{\bf Selected Environment Variables}\\
\hline
{\it variable}& {\it sample value}& {\it usage}\\
\hline
terminal& ``vt100''& default terminal device\\
printer& ``printronix''& default line printer device\\
stdgraph& ``vt640''& name of graphics terminal device\\
stdplot& ``versatec''& batch plotter device\\
stdvdm& ``uparm\$vdm''& name of graphics metacode file\\
stdimage& ``iism75''& image display device\\
clobber& no& clobber (overwrite) output files\\
filewait& yes& wait for busy files to become available\\
\hline
\end{tabular}
\end{center}
\medskip
\noindent
Clearly, the permissible names of devices are site dependent; for a list of
the devices available at a particular site the user should consult their
\irafname{IRAF Guru} (or look in the \filename{TERMCAP} and \filename{GRAPHCAP}
files in the IRAF logical directory \filename{DEV}).
Among the set of environment variables that control the operation of
the CL is a subset of variables that define the user environment. These
variables describe the user's home and scratch directories, terminal
type, and editor preference. Because these values describe a user's-eye
view of IRAF, they can be thought of as \emphasize{customization} variables
and can be \usertype{set} in the \filename{LOGIN.CL} file to your
preferred values.
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
\multicolumn{3}{|c|}{\bf User Environment Variables}\\
\hline
{\it variable}& {\it sample value}& {\it usage}\\
\hline
editor& ``vi'' & default editor mode\\
home& ``/{\it user}/iraf/'' \footnotemark & user home directory\\
uparm& ``home\$uparm/''& user scratch directory\\
imdir& \emphasize{system-dependent}&directory where bulk data is stored\\
imtype& ``imh'' & default image type (header file extension)\\
userid& {\it user}& user identification name (for output)\\
\hline
\end{tabular}
\end{center}
\footnotetext{ {\bf VMS :} an equivalent VMS example might be
``DISK\bsl\$1:[USER.IRAF]''. Note that any dollar sign characters appearing
in host filenames must be escaped in IRAF since the dollar sign is a reserved
character in IRAF filenames.}
\noindent
The \filename{HOME} directory specification, and possibly an
\filename{IMDIR} declaration should be the \emphasize{only} places in
your \filename{LOGIN.CL} file where any system specific names appear
at all. All of the IRAF name references (except a single root reference)
are processed by the virtual name mapping algorithms. If this same
mechanism is used for all user files as well, then only IRAF
virtual filenames need to be referenced once the root directory
has been properly specified.
The default \emphasize{uparm} declaration
assumes that a \filename{UPARM}
subdirectory has been set up in your login directory; the \usertype{mkiraf}
command described earlier (\S 2.1) sets this up for you. If a \filename{UPARM}
subdirectory does \emphasize{not} exist, the CL will refuse to update
user parameters and will issue a warning message.
\subsection{File and Directory Names}
\ppind
The IRAF system employs \irafname{virtual file} names so that all file
references will look the same on any computer, and IRAF primitives convert
virtual filenames into their host operating system equivalents. In general,
either the IRAF virtual filename or the operating-system-dependent filename
may be used in a command entered by the user, but users should avoid
the use of OS-specific names wherever possible. Internally IRAF itself
uses only virtual filenames for reasons of transportability.
Note that filename mapping does not operate automatically for virtual file
names that are passed as parameters to foreign (host system) tasks, but a CL
intrinsic function \taskname{osfn} will perform the mapping if called
explicitly on the command line. The host task must be declared as an IRAF
\taskname{foreign task} (\S 5.6) for this to work. There is no provision
for filename mapping when the regular OS escape mechanism (\S 4.1) is used.
The environment variables described in the preceding section play a fundamental
role in the mapping of virtual filenames. Environment variables define
the logical directories that are used to create host operating system
specific names from logical names. An example of a virtual filename
is the default logfile, \filename{HOME\$LOGFILE.CL}.
The \filename{HOME} field, delimited by the `\$' character, is the logical
directory; the file name within that directory is \filename{LOGFILE.CL}.
Successive translations of `\$'-delimited logical names are performed until the
operating system dependent name has been generated. Names such as
\filename{HOME\$UPARM/} are \emphasize{directory} references; the trailing `/'
indicates that a filename or sub-directory name may be appended to produce
a legal file or directory pathname.
\subsubsection{File Name Templates and Metacharacters}
\ppind
Although filenames cannot be abbreviated the way commands can,
pattern matching templates can be constructed that
refer to many files. You need only type a
short string (the pattern) that serves as a \emphasize{template}, and all
files whose names match the template are selected. All of the IRAF
functions that process filenames (and this is most of them) use the
same function to expand filename templates into a list of files.
The pattern matching \irafname{metacharacters} are a super-set of those
used in the UNIX and VMS operating systems. To print all files having
the extension \filename{.CL}, type:
\begin{quotation}\noindent
\comptype{cl>} \usertype{lprint $*$.cl}
\end{quotation}
\noindent
To page through all files in the logical directory \filename{FIO}
with the \filename{.X} extension, type:
\begin{quotation}\noindent
\comptype{cl>} \usertype{page fio\$$*$.x}
\end{quotation}
\noindent
The filenames matched by the file template are passed to the \usertype{page}
task which pages through the set of files. As each file is accessed, the VOS
filename translation facilities are used internally to generate the host
system filename, which is passed to the kernel to physically open the file.
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
\multicolumn{3}{|c|}{\bf Pattern Matching Metacharacters} \\
\hline
{\it Meta-char}& {\it Meaning}& {\it Example}\\
\hline
$*$ & Match zero or more characters & $*$.cl \\
\lbox...\rbox & Any character in class & \lbox a-z\rbox \\
\lbox \upa...\rbox & Any character not in class & \lbox \upa A-Z\rbox \\
? & Match any single character & a?c \\
\{...\} & Ignore case for the enclosed string & \{Lroff\} \\
@{\it file} & Read filenames from a list file& @listfile \\
\hline
\end{tabular}
\end{center}
\noindent
To delete a named list of files, type:
\begin{quotation}\noindent
\comptype{cl>} \usertype{delete file1,file2,file3}
\end{quotation}
\noindent
Note that the list of filenames is separated by commas \usertype{','}
\emphasize{with no intervening blanks}.
This causes the individual filenames to be treated as one list-form
parameter rather than to be processed as three separate parameters.
A blank is treated as a delimiter by the parser, and thus may not appear
in a list-form parameter unless the list is enclosed in quotes.
The following is equivalent to the previous example, except that no warning
will be issued if any of the three files does not exist, since we are asking
the system to find all files that match the template, rather than naming the
files explicitly:
\begin{quotation}\noindent
\comptype{cl>} \usertype{delete file\lbox123\rbox}
\end{quotation}
\noindent
Consider the following simple command:
\begin{quotation}\noindent
\comptype{cl>} \usertype{delete filex}
\end{quotation}
\noindent
The name ``filex'' given here is actually ambiguous; it could be either the
name of a file (a string constant) or the name of a string parameter
set to the name of the file to delete. In this simple and common case,
the CL will quietly assume that ``filex'' is the \emphasize{name} of the
file. If the identifier \usertype{filex} is really the \emphasize{name}
of a variable, it will have to be parenthesized to force it to be evaluated.
Either of the following forms are equivalent to this command and both are
unambiguous requests to delete the file named \filename{FILEX}:
\begin{quotation}\noindent
\comptype{cl>} \usertype{delete 'filex'}\\
\medskip
\comptype{cl>} \usertype{delete ('filex')}
\end{quotation}
\noindent
Note that within parentheses the \emphasize{string} \usertype{'filex'}
must be typed as shown, with quotes, or the CL will attempt to process
it as a variable name, causing a runtime error if there is no such variable
currently defined within the scope of the \taskname{delete} task.
The following command is also unambiguous, and it specifies that the CL
is to take the name of the file from the \emphasize{parameter} ``filename'':
\begin{quotation}\noindent
\comptype{cl>} \usertype{delete (filename)}
\end{quotation}
Note that in many of these examples, a \emphasize{single} string
type argument, viz. the file matching template with metacharacters,
is used to refer to a list of files.
This convention is employed by all IRAF tasks which
operate on lists of files. Be careful not to confuse a file list template
with the argument list itself. Thus:
\begin{quotation}\noindent
\comptype{cl>} \usertype{delete file,file2,prog.$*$}
\end{quotation}
\noindent
is perfectly acceptable, and does what the next example does:
\begin{quotation}\noindent
\comptype{cl>} \usertype{delete 'file1, file2, prog.$*$'}
\end{quotation}
\noindent
as long as there are no blanks between elements of the first name list.
If blanks were inadvertently included in the unquoted template string the
CL would interpret the template as several string arguments, probably causing
an error something like ``\comptype{too many positional arguments}''.
The list file approach is useful when it is difficult to specify a template
for the desired set of files, when the same set of files will be operated
upon several times, when a very large number of files are to be operated
upon, or when a list is already available. The file list may be generated
by the editor, or by a task such as \taskname{files}, e.g.:
\begin{quotation}\noindent
\comptype{cl>} \usertype{files *.im,run[1-4].* $>$ listfile}
\end{quotation}
\noindent
The textfile \filename{LISTFILE} may then be referenced in a filename template
as \usertype{@listfile} to operate upon the listed files. A variation on
the listfile approach is \usertype{@STDIN} (must be upper case), which
allows the filenames to be typed in when the task begins running.
Some tasks use the filename template mechanism to generate the names of a
\emphasize{new} set of \emphasize{output} files. The filename template
expansion code provides two operators for generating new filenames from
old ones. The file template \emphasize{operators}, which are used to
construct new filenames, should not be confused with the pattern matching
\emphasize{metacharacters}, which are used to match a subset of an existing
set of files.
The first and simplest operator is the string concatenation operator
\comptype{//}. This may be used to concatenate a string suffix to the
\emphasize{root} field of a filename, to concatenate a filename to a string
prefix, to concatenate two filenames, or some combination of the above.
For example,
\begin{quotation}\noindent
\comptype{cl>} \comptype{files lib\$*.com$//$\_o}
\end{quotation}
\noindent
will produce a new list of files by appending the string \comptype{"\_o"} to
the root of each filename matched by the template at the left.
The second and last operator is the string substitution operator
\comptype{\%}. If a sequence of the form \comptype{\%a\%b\%} is inserted
somewhere in a file template, the string \usertype{a} will participate in
the pattern matching operation, but will be replaced by \usertype{b} in the
generated filename. Either \usertype{a} or \usertype{b} may be omitted to
insert or delete fields from a filename. For example,
\begin{quotation}\noindent
\comptype{cl>} \comptype{files lib\$*\%\%\_o\%.com}
\end{quotation}
\noindent
is equivalent to the concatenation operation illustrated in the preceding
example. The command
\begin{quotation}\noindent
\comptype{cl>} \comptype{files lib\$*.\%com\%dat\%}
\end{quotation}
\noindent
would find all the \filename{.COM} files in the logical directory
\filename{LIB}, generating a new list of files with the extension
\filename{.DAT} substituted for \filename{.COM}.
All IRAF tasks that use pattern matching or template expansion use the same
syntax and metacharacters as in the examples given here for filename templates.
This includes, for example, the use of templates in the \taskname{help} task
to locate manual pages, and the use of pattern matching in the \taskname{match}
task to search text files for lines that match a pattern.
\subsubsection{Directories and Path Names}
\ppind
It is often useful to employ several different directories as an aid to
organizing your data. For instance, you may have one directory for M87 data,
and one for M8 data, or, as was set up for you by the \usertype{mkiraf} command,
a login directory \filename{HOME} and a scratch directory \filename{UPARM}.
New directories may be created with \usertype{mkdir}; use \usertype{chdir}
or \usertype{cd} to change the default directory, and \usertype{back} to
return to the most recent default directory.
For example, to display the pathway through the system to your current
default directory, type:
\begin{quotation}\noindent
\comptype{cl>} \usertype{path}
\end{quotation}
\noindent
To change to a new default directory, type:
\begin{quotation}\noindent
\comptype{cl>} \usertype{chdir }{\it newdir}
\end{quotation}
\noindent
where {\it newdir} may be an IRAF logical directory name defined
with a \usertype{set} command, an IRAF pathname to the directory,
or a host system directory name (provided any dollar sign characters
therein are escaped).
The \usertype{mkdir} command can be used to create a new sub-directory
of the current directory:
\begin{quotation}\noindent
\comptype{cl>} \usertype{mkdir m87}
\end{quotation}
\noindent
To define a logical directory name (``m87'') for this subdirectory
of your home directory, use the following set command (note the trailing '/'):
\begin{quotation}\noindent
\comptype{cl>} \usertype{set m87 = 'home\$m87/' }\footnotemark
\end{quotation}
\footnotetext{ {\bf VMS :} IRAF supports logical names for
files and directories that may contain mixed cases and special
characters. However, to avoid unpleasant surprises,
we recommend that for root directories you use only names valid
for the underlying operating system.}
\noindent
Once this logical name mapping has been established, you may type either
of the following commands to change the default
directory to the ``m87'' directory (note \usertype{chdir} may be
abbreviated \usertype{cd}):
\begin{quotation}\noindent
\comptype{cl>} \usertype{chdir m87} \\
\medskip
\comptype{cl>} \usertype{cd home\$m87}\footnotemark
\end{quotation}
\footnotetext{ {\bf VMS :} The characters \comptype{\$} and \comptype{[},
commonly used in VMS device and directory names, will cause a conflict
if VMS file or device names using them are passed to IRAF tasks since these
characters have a special meaning in IRAF filenames and filename templates.
If either of these characters is used in a VMS filename passed to an IRAF
program, the character must be escaped to avoid interpretation as a VOS
metacharacter, e.g., \comptype{page usr\bsl\$0:\bsl[iraf.local]login.cl}.}
\noindent
If you type \usertype{chdir} or \usertype{cd} without any arguments, the
default directory will be set to your ``home'' directory.
Once a logical directory has been defined, the IRAF pathname notation may
be used to reference any file or directory in the vicinity of the new logical
directory. For example, the following command would page the file CURSOR.KEY
in the subdirectory SCR of the subdirectory LIB of the IRAF root directory
IRAF, a predefined logical directory:
\begin{quotation}\noindent
\comptype{cl>} \usertype{page iraf\$lib/scr/cursor.key}
\end{quotation}
The current directory and the directory one level up from the current
directory may be referenced in pathnames via the synonyms ``\usertype{.}''
and ``\usertype{..}''. For example, if the current default directory is PKG,
a subdirectory of LIB like SCR in the preceding example, the path to the
CURSOR.KEY file could be entered as follows:
\begin{quotation}\noindent
\comptype{cl>} \usertype{page ../scr/cursor.key}
\end{quotation}
It is not necessary to change the default directory to reference
files located in another directory. Your login directory, for example, has
the logical name \filename{HOME\$} assigned to it.
The following command would page through the \filename{LOGIN.CL}
file in your home directory, regardless of the current default directory:
\begin{quotation}\noindent
\comptype{cl>} \usertype{page home\$login.cl}
\end{quotation}
\noindent
The logical directory names (\filename{UPARM} and \filename{IMDIR} are examples
of directories that are normally appended to the \filename{HOME}
directory, and you may set up other logical directories as required.
The names of all of the standard IRAF system directories are defined
automatically when the CL starts up, and may be listed with the
\taskname{set} command.
\subsubsection{Virtual Filename Processing}
\ppind
Virtual filenames are used throughout IRAF and the CL in preference
to operating system specific names. The obvious reason for this is
to isolate OS specific interfaces to a small set of locations, as
a way of ensuring commonality across operating systems and as an
aid to portability. There is an obvious benefit to the user as well,
in that filename references will look the same within IRAF regardless
of the host environment. Operating system specific names must
eventually be generated, but the details of these operations are
best buried in dedicated interface routines.
The only place where OS specific names need appear at the user level is
in file system directory names and in references to system physical devices.
Even here, the use of OS specific names should be isolated to only
one or two root directory names.
The other place where OS names must appear is calls to operating
system routines or to external programs that are accessed from within
IRAF via the OS escape mechanism (\S 4.1). The \taskname{pathnames} task
and the \taskname{osfn} intrinsic function are used to translate IRAF virtual
filenames into host system filenames.
Either of the following commands will print the fully qualified OS name
for the file \filename{HOME\$LOGIN.CL}.
\begin{quotation}\noindent
\comptype{cl>} \usertype{path home\$login.cl}\\
\medskip
\comptype{cl>} \usertype{= osfn ('home\$login.cl')}\\
\end{quotation}
\noindent
The \taskname{pathnames} task writes the translated filename on its standard
output, while \taskname{osfn} returns the translated filename as the function
value. The \usertype{pathnames} task will also expand filename templates,
and thus can be used to generate the OS names for a list of files:
\begin{quotation}\noindent
\comptype{cl>} \usertype{path home\$ss433.*\ $>$ ss433files.list}
\end{quotation}
\noindent
will generate a list of all of the files in directory \filename{HOME}
that match the template, and will write the fully qualified OS names
of these files into \filename{SS433FILES.LIST}. This ASCII file can
be edited as necessary, and used as list-structured input to other
IRAF functions (\S 2.3, \S 6.9, \S 7.3).
The most common use of the \taskname{pathnames} task is probably to print
the current default directory, which is its function when called with no
arguments on the command line.
\subsection{Image Data}
\ppind
An IRAF \emphasize{image} is an N-dimensional data array with an associated
\emphasize{image header} describing the physical and derived attributes of
the image. The content of the header tends to be very data or application
specific. The datatype selected to store the \emphasize{pixels} (data values)
is also application dependent, and a variety of choices are provided.
Images of up to seven dimensions are currently supported, although
in practice most images are either one or two dimensional, and most programs
are written to operate upon one or two dimensional images. Any IRAF program
can be used to operate upon a \emphasize{section} of lesser dimension
(or extent) than the full image, using the \emphasize{image section} notation
discussed in \S 4.4.3, hence the dimensionality of the algorithm implemented
by a program need not prevent use of the program on images of higher dimension.
\subsubsection{Image Names and Storage Formats}
\ppind
The notation used to refer to images is similar to that used to refer to
files, except that images are more complex objects than files and hence a
somewhat more complex notation is required. Most of the file, directory,
and pathname notation discussed in \S4.3 carries over to images.
Sets of images are referred to by an \emphasize{image template} notation
which is an extension of the file template notation discussed in \S4.3.1.
In most, but not all, cases, an IRAF image is stored on disk in two separate
files, one containing the image header and the other containing the pixels.
The basic image name is the filename of the header file. The filename of an
image header file always has an extension specifying the format in which the
image is physically stored on disk. \footnote{In versions of IRAF prior to
V2.3, only one physical image storage format was supported, hence image header
files did not have extensions.} Two storage formats are currently supported,
the old iraf format (OIF) and the SDAS group data format (STF). The old IRAF
format images have the extension \filename{IMH}. The STF images may have any
three character extension ending in \filename{H}, e.g., \filename{HHH}
(the extension \filename{IMH} is reserved for OIF images, of course).
Both types of images may be accessed at any time, with the extension being
used to identify the physical storage format to the IRAF software.
For example, the IRAF system is distributed with a standard OIF format test
image \filename{PIX} stored in the system directory \filename{DEV}. The full
filename of the header file is \filename{DEV\$PIX.IMH}. To make a copy of
this image in the current directory we could load the \taskname{images}
package and enter the following command:
\begin{quotation}\noindent
\comptype{cl>} \usertype{imcopy dev\$pix pix}
\end{quotation}
\noindent
or since we don't want to change the image name,
\begin{quotation}\noindent
\comptype{cl>} \usertype{imcopy dev\$pix .}
\end{quotation}
\noindent
Note that we did not have to specify the image type extension in the copy
operation. The extension is optional whenever a single image is referenced;
in image templates, the template must match the full filename of each image
as it appears in a directory listing, hence the extension is required in
image templates.
Sometimes it is necessary to specify the image type extension to force an
image of a certain type to be created. For example,
\begin{quotation}\noindent
\comptype{cl>} \usertype{imcopy dev\$pix pix.bah}
\end{quotation}
\noindent
would create an STF format copy of the standard test image in the current
directory.
When making a copy of an existing image, the new image will have the same
format as the old image unless an extension is specified in the output image
name. When creating a new image from scratch, e.g., when reading a data
tape to disk, the default image type is determined by the value of the CL
environment variable \filename{IMTYPE}, the value of which is the three
character default image type extension. If \filename{IMTYPE} is not defined,
the default value is \usertype{imh}, i.e., an OIF format image will be
created. To change the default to be to create an STF format image, add
a command such as
\begin{quotation}\noindent
\comptype{cl>} \usertype{set imtype $=$ hhh}
\end{quotation}
\noindent
to your \filename{LOGIN.CL} file.
\subsubsection{Image Templates}
\ppind
Image templates are equivalent to filename templates except that the character
\comptype{`['}, a pattern matching character in filename templates, has a
different meaning in image templates, as we shall see in the next section.
\footnote {If you really want to perform file template style character class
expansion in an image template, use the operator \comptype{![} instead
of \comptype{[}. The conventional escape mechanism, i.e., \comptype{\bsl[},
is used to include the \comptype{[} in the \emphasize{filename}, as in a
filename template.}
\noindent
For example, given a directory containing the files
\begin{verbatim}
irs.log irs.0030.imh irs.0031.imh irs.0032.imh
\end{verbatim}
\noindent
the template \usertype {irs.$*$.imh} would match the three image files,
whereas \usertype{irs.$*$} would match the \filename{LOG} file as well,
causing \taskname{imheader} to complain about an illegal format image in
its input list.
\subsubsection{Image Sections}
\ppind
All IRAF programs which operate upon images may be used to operate on
the entire image (the default) or any section of the image.
A special notation is used to specify \irafname{image sections}. The section
notation is appended to the name of the image, much like an
array subscript is appended to an array name in a conventional programming
language. Note that array or image section \emphasize{index references}
are integer only in pixel coordinates, but that the data may be of any valid
type.
\begin{quote}
\begin{tabular}{ll}
{\it section}& {\it refers to}\\
\\
pix& whole image\\
pix[]& whole image\\
pix[i,j]& the pixel value (scalar) at [i,j]\\
pix[$*$,$*$]& whole image, two dimensions\\
pix[$*$,-$*$]& flip y-axis\\
pix[$*$,$*$,b]& band B of three dimensional image\\
pix[$*$,$*$:s]& subsample in y by S\\
pix[$*$,l]& line L of image\\
pix[c,$*$]& column C of image\\
pix[i1:i2,j1:j2]& subraster of image\\
pix[i1:i2:sx,j1:j2:sy]& subraster with subsampling
\end{tabular}
\end{quote}
\noindent
A limited set of coordinate transformations may be specified using image
sections, but please observe that transpose is \emphasize{not} one of them.
The ``match all'' (asterisk), flip, subsample, index, and range notations
shown in the table may be combined in just about any way that makes sense.
As a simple example:
\begin{quotation}\noindent
\comptype{cl>} \usertype{graph pix[$*$,10]}
\end{quotation}
\noindent
will graph line 10 of the image \filename{PIX}.
To generate a contour plot of an 800-pixel square image
subsampled by a factor of 16 in both dimensions:
\begin{quotation}\noindent
\comptype{cl>} \usertype{contour pix[$*$:16,$*$:16]}
\end{quotation}
\noindent
To display the fifth $x-z$ plane of a three dimensional image named
\usertype{cube} on frame 1 of the image display device:
\begin{quotation}\noindent
\comptype{cl>} \usertype{display cube[$*$,5,$*$] 1}
\end{quotation}
\noindent
The image section string is part of the image name and is processed by
the IRAF system software (rather than by each applications program),
hence image sections can be used with all IRAF programs. A section can
be used to write into a portion of an existing output image, as well as to
read from an input image.
\subsubsection{The OIF Image Format}
\ppind
The old IRAF image format (OIF) is the original IRAF image format,
unchanged since it was first used in the beginning of the project.
It is called the ``old'' format in anticipation of its eventual replacement
by a new format to be layered upon the planned IRAF database facilities.
The OIF format is the current standard IRAF image format and is the format
used to test the IRAF image processing software at NOAO.
In the OIF format, each image is stored in a distinct pair of files, the
header file (extension \filename{IMH}) and the pixel file (same root name as
the header file, extension \filename{PIX}). The pixel file need not reside in
the same directory as the header file; by default all pixel files are
created in a user directory on a scratch disk device to permit a different
file quota, file expiration, and backup policy to be employed than is used
for the smaller, more permanent ordinary user files.
The CL environment variable \filename{IMDIR} determines where OIF pixel files
will be created. \filename{IMDIR} is a required parameter and is normally
defined in the user's \filename{LOGIN.CL} file. The value of \filename{IMDIR}
is only used when the pixel file is created; if the value of \filename{IMDIR}
is later changed, new pixel files will be created in a different directory,
but the system will still be able to find the pixel files of the older images.
By default, the \taskname{mkiraf} script will create an image storage
directory for the user on a public scratch device and place the host pathname
of the new directory in the user's \filename{LOGIN.CL} file. For example,
on a UNIX system, a typical set environment statement might be:
\begin{quotation}\noindent
\usertype{set imdir $=$ $/$tmp2$/$iraf$/$user$/$}
\end{quotation}
\noindent
which will cause the pixel files to be created in the named host directory,
regardless of the directory in which the image header file resides.
As an option, we can request that the pixel file be placed in the
\emphasize{same} directory as the header file:
\begin{quotation}\noindent
\usertype{set imdir $=$ HDR\$}
\end{quotation}
\noindent
or in a subdirectory of the header file directory, e.g., subdirectory
\filename{PIXELS}:
\begin{quotation}\noindent
\usertype{set imdir $=$ HDR\$pixels$/$}
\end{quotation}
\noindent
Note that the reserved logical directory name \filename{HDR} must be upper
case, and that a trailing slash is required if the subdirectory option is used.
The subdirectory will be created automatically by the system when the first
pixel file is created, if the directory does not already exist.
The \filename{HDR} option should \emphasize{only} be used if the header file
itself is created in a directory on a scratch device; it should always be used
if the image is created on a remote node in the local network.
\subsubsection{The STF Image Format}
\ppind
The STF image format is the format used by STScI to store Space Telescope
image data. IRAF provides a dedicated image kernel to read and write this
format so that sites reducing binary ST data do not have to carry out expensive
format conversions to be able to access the data from within IRAF. SDAS
users should note that the SDAS software can \emphasize{only} access STF
format images, hence the STF format must be used if you plan to make extensive
use of SDAS. Reductions involving only IRAF programs should not use the STF
format, since the OIF format is simpler and more efficient, and is the format
used to test the IRAF software.
In the STF format, an image or a \emphasize{group} of similar images may be
stored in a pair of files, the image header file (extension \usertype{??H}),
and the associated pixel storage file (extension \usertype{??D}). If multiple
images are stored in a group format image, all member images share the same
group header. The group header file is a special VMS format text file which
can be examined by \taskname{page} and \taskname{type}, as well as with
\taskname{imheader}. Each member image in a group format image also has its
own private binary format header, called the group parameter block. The STF
image format supports only single precision real pixels, since that is what
SDAS programs require.
IRAF programs consider images to be independent entities, with any associations
between images being left up to the user. When a member image of an STF
group format image is accessed from an IRAF program, IRAF constructs the image
header of the member image by concatenating the group header to the group
parameter block for the member image; no distinction is made between the two
classes of header parameters once the image has been opened.
To refer to a specific member image of a group format image, the group
subscript must be specified in the image name. If there is an image section
as well, it comes after the group subscript. For example, if \filename{WFPC}
is an STF group format image,
\begin{quotation}\noindent
\comptype{cl>} \usertype{implot wfpc[3]}
\end{quotation}
\noindent
would call up the interactive image plotting task \taskname{implot} on group
3 of the group format image. If no subscript is specified, the default is
group 1. To plot the same image with the lines flipped end for end, we add
an image section:
\begin{quotation}\noindent
\comptype{cl>} \usertype{implot wfpc[3][$-*,*$]}
\end{quotation}
\noindent
To create a new group format image, we must preallocate space for all the
member images, all of which must be the same dimensionality, size, and
datatype. For example,
\begin{quotation}\noindent
\comptype{cl>} \usertype{imcopy wfpc wfpc2[1$/$10]}
\end{quotation}
\noindent
would create a new group format image \filename{WFPC2} with the same
dimensionality, size, and group parameter block as the existing STF image
\filename{WFPC}, then copy the pixels from \filename{WFPC} to
\filename{WFPC2[1]}. The new image would inherit the header of the old
image as well. Once a new group format image has been created, the remaining
member images may be written into by specifying the group subscript in the
output image name passed to an IRAF program. The group count
(\usertype{$/$10}) should be omitted, else IRAF will try to create a new
group format image, rather than write into one of the member images of
an existing group. Note that member images cannot be added or deleted
once a group format image has been created.
\newpage
\section{Advanced Topics in the CL}
\ppind
In addition to the basic facilities already described,
the CL permits user control over many aspects of the environment.
This includes direct control over the CL itself, control over user tasks
and background processes, the job logfile and the command history mechanism.
These features and others will be of use to the more advanced user
and enable user customization of interactions with the system.
\subsection{CL Control Parameters}
\ppind
The CL is itself a task which has a set of parameters that
are used to direct its execution. For example, if you wish to keep
a permanent record of all the commands you enter, the CL will do this
if you set its boolean parameter \taskname{keeplog} to yes. (Boolean
parameters can assume only the values \emphasize{yes} or \emphasize{no}.)
Simply type:
\begin{quotation}\noindent
\comptype{cl>} \usertype{keeplog = yes}
\end{quotation}
\noindent
and all subsequent commands will be written to the log file.
The name of this file is defined by the
string parameter \taskname{logfile} which defaults to the filename
\filename{HOME\$LOGFILE.CL}. The name of the logfile may be changed
by assigning a new value to the parameter, e.g.:
\begin{quotation}\noindent
\comptype{cl>} \usertype{logfile = "commands.log"}
\end{quotation}
The important CL parameters which you may wish to alter or otherwise
access are described in the table below.
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
\multicolumn{3}{|c|}{\bf CL Parameters}\\
\hline
{\it parameter} & {\it typical value} & {\it function}\\
\hline
echo & no & echo CL command input on stderr? \\
ehinit & (see manpage) & ehistory options string \\
epinit & (see manpage) & eparam options string \\
keeplog & no & record all interactive commands in logfile? \\
logfile & ``home\$logfile.cl'' & name of the logfile \\
logmode & (see manpage) & logging control \\
menus & yes & display menu when changing packages? \\
mode & "ql" & default mode for servicing parameter queries \\
notify & yes & send done message when bkgrnd task finishes? \\
szprcache & 3$-$4 & size of the process cache \\
\hline
\end{tabular}
\end{center}
\medskip
\noindent
A full list of CL parameters can be obtained with the \emphasize{lparam}
command, or by typing the command \usertype{help language.cl}. The latter
provides a brief description of each CL control parameter including references
to \taskname{language} package manual pages containing more detailed
information.
Changes that you make to any of the CL task parameters by assignment during
a session will be lost when you log out of the CL.
This is in contrast to the parameters of a normal task, which are learned
by the CL. If you want the CL to ``remember'' values of CL parameters,
you should initialize them to your personal default values in your
\filename{LOGIN.CL} file and they will be reestablished for you each time
you log in.
\subsection{Setting the Editor Language and Options}
\ppind
The parameter editor (\usertype{eparam}) command and the history
editor (\usertype{ehistory}) both use the same simple set of edit commands
and a choice of editor languages is available. The command:
\begin{quotation}\noindent
\comptype{cl>} \usertype{set editor = emacs}
\end{quotation}
\noindent
will set the edit mode for both editors to use the Emacs set of keystrokes.
This also changes the editor that is invoked when
you issue the \usertype{edit} command, so that all of the editor interfaces
that are available will appear to operate in the same way.
Editor choices, with their associated key bindings, are:
\begin{itemize}
\item EDT (the default for VMS devotees)
\item Vi (ditto for their UNIX counterparts)
\item Emacs (which runs on either system)
\end{itemize}
For convenience, all of these editor choices support
use of the cursor keypad keys and the \key{DELETE} key; the
ambitious user may define his own personal set of command key bindings.
The bindings that are available by default in IRAF are shown in an
Appendix (\S A.4). The default editor language that IRAF will start
with is as shown above, chosen for compatibility with the host operating
system. You may, of course, include a \usertype{set} command in
your \filename{LOGIN.CL} file to establish your own preferred editor.
The edit facilities provided within IRAF are limited in scope, since
they are only intended to facilitate manipulation of user accessible
internal structures, task parameter blocks and history file. IRAF
has not implemented a full scale text editor, so the \usertype{edit}
command invokes the standard system editor which you choose by setting
the \usertype{editor} parameter.
A host system editor must be used for all major text manipulations,
but since it is invoked from within the IRAF environment the continuity
of your session is not lost.
In addition to selecting the editor language to be used, there are a few user
settable options available to control the operation of the \taskname{eparam}
and \taskname{ehistory} tasks. These options are set by setting the string
values of the CL parameters \taskname{epinit} and \taskname{ehinit}.
For example, setting the \taskname{verify} option for \taskname{ehinit}
will cause the history mechanism to pause waiting for a command to be
edited or inspected, before executing the command.
Read the manual pages for the \taskname{eparam} and \taskname{ehistory} tasks
for a full description of these control options.
\subsection{The History Mechanism}
\ppind
The CL history mechanism keeps a record of the commands you enter and
provides a way of reusing commands to invoke new operations with a minimum of
typing. The history mechanism should not be confused with the logfile;
the history mechanism does not make a permanent record of commands,
and the logfile cannot be used to save typing
(except by using the editor on it after the end of the session).
With the history editor, previous commands can easily
be edited to correct errors, without the need to retype the entire command.
The \usertype{history} command is used to \emphasize{display} command lines.
By default, the last 15 commands entered are printed, each preceded by
the command number. To show the last \emphasize{n} commands,
add the argument \usertype{n} to the \usertype{history} command line:
\begin{quotation}\noindent
\comptype{cl>} \usertype{history 3} \\
\comptype{101 urand 200 2 \pipe graph po+ marker=circle szmarker=.03} \\
\comptype{102 help graph \pipe lprint} \\
\comptype{103 history} \\
\comptype{cl>}
\end{quotation}
\noindent
and note that this number (\emphasize{n}) will become the new default.
If you ask for a negative number of commands (\emphasize{-n}),
the default will not change.
The \usertype{history} command allows previous command sequences to be
displayed, but a related mechanism must be used to re-execute, or to
edit and execute, commands. You can use the history file \emphasize{editor}
by issuing the command \usertype{ehistory}. Once you are in the history editor,
the cursor (arrow) keys can be used to move about in the history file. You
may select any command and edit it using the simple edit commands described
previously (\S 3.2.3) for the \taskname{eparam} task. Such functions as
deletions and insertions of words or characters, delete to end of line, and
a simple string search and replace capabilities are provided.
The Appendix lists the full range of commands that are supported.
The edited command is executed by hitting
\key{RETURN}. Note that it is a \emphasize{new} command and, as such, it is
appended to the history file. The current contents of the history file
are not changed.
It is possible to recall \emphasize{individual} commands and edit them;
the special character `\upa' or the \usertype{ehistory} command may be
used for this. Given the history record sequence shown above,
any of the following commands could be used to fetch command 101:
\begin{quotation}\noindent
\begin{tabbing}
\comptype{cl>} \usertype{\upa 101} \hspace{2cm} \= \#~fetch~command~101 \\
\medskip
\comptype{cl>} \usertype{ehist -3} \> \#~fetch~third~command~previous \\
\medskip
\comptype{cl>} \usertype{\upa ur} \> \#~fetch~command~starting~with~``ur'' \\
\medskip
\comptype{cl>} \usertype{ehist ?mark?} \> \#~fetch~command~containing~``mark''
\end{tabbing}
\end{quotation}
The history command \usertype{\upa ur} finds the last command
\emphasize{beginning} with the string ``ur'', while the command
\usertype{ehist ?mark?} finds the last command \emphasize{containing} the
string ``mark'' (the trailing `\usertype{?}' is optional if it is the
last character on the line). A single `\upa' fetches the last command
entered. Successive `\upa' commands
will fetch the next preceding command lines from the history file.
The selected command is echoed on the screen, with the cursor pointing at it.
At that point, the command can be executed just by typing \key{RETURN},
or it may be edited. The standard set of editor operations also apply
when you edit a command in single line mode. Note that compound statements
(those enclosed in pairs of braces~``\{~$\ldots$~\}'') are treated as a
\emphasize{single} statement by the editor. Only one command line (which may
be a compound statement) can be edited at a time with the history editor.
Sometimes you will want to reuse the \emphasize{arguments} of a previous
command. The notation `\upa\upa' refers to the \emphasize{first} argument
of the last command entered, `\upa\$' refers to the \emphasize{last} argument
of the command, `\upa$*$' refers to the whole argument list, `\upa0' refers
to the taskname of the last command, and `\upa$N$' refers to argument
\emphasize{N} of the last command entered. Thus,
\begin{quotation}\noindent
\comptype{cl>} \usertype{dir lib\$$*$.h,home\$login.cl} \\
\comptype{cl>} \usertype{lprint \upa\upa}
\end{quotation}
\noindent
displays a table of the files specified by the template, and then prints
the same files on the line printer.
One of the most useful features of the history mechanism is the ability to
repeat a command with additional arguments appended. Any recalled command
may be followed by some extra parameters, which are appended to the command.
For example:
\begin{quotation}\noindent
\comptype{ut>} \usertype{urand 200 2 \pipe graph po$+$} \\
\comptype{ut>} \usertype{\upa\upa title = '200 random numbers'} \\
\comptype{urand 200 2 \pipe graph po$+$ title = '200 random numbers'}
\end{quotation}
\noindent
in this case, the notation `\upa\upa' refers to the last
\emphasize{command} entered.
The notation is unambiguous because the `\upa\upa' appears at the start of
the command line. Do not confuse it with the use of `\upa\upa' to reference
the first argument.
\subsection{Foreign Tasks}
\ppind
The foreign task mechanism provides an alternative to the OS escape mechanism
for sending commands to the host operating system. The advantage of the
foreign task mechanism is that it allows foreign commands to be made available
within the IRAF environment just as if they were normal IRAF tasks.
Such commands may be abbreviated, their output may be redirected or piped,
the commands may be run in batch mode, and the argument list is parsed and
evaluated by the CL, hence may contain any valid CL expression. Users should
beware, however, that IRAF virtual filenames appearing in the argument list
of a foreign task are not normally translated to their host equivalents, since
IRAF knows nothing about the argument list of a foreign task
(the \taskname{osfn} intrinsic function may be referenced in the argument
list to explicitly perform the translation, if desired).
To declare several foreign tasks with the same names in IRAF as in the host
environment, use the following form of the \taskname{task} statement:
\begin{quotation}\noindent
\comptype{cl>} \usertype{task \$mail \$grep $=$ \$foreign}
\end{quotation}
\noindent
This declares the new tasks \taskname{mail} and \taskname{grep} in the current
package, whatever that may be. If the current package is subsequently exited,
the task declarations will be discarded.
To declare a foreign task with a more complex calling sequence, use the
following form of the foreign task declaration:
\begin{quotation}\noindent
\comptype{cl>} \usertype{task \$who $=$ "\$show users"}
\end{quotation}
\noindent
This example would be used on a VMS host to map the IRAF foreign task
\taskname{who} to the VMS command \usertype{show users}. If there are
any arguments on the command line when the task is called, they will be
converted to strings and appended to the command prefix given.
The \filename{LOGIN.CL} file contains a default \filename{USER} package
containing examples of several foreign task statements which may prove
useful on the local host. Users should feel free to modify or extend
the \filename{USER} package, since it is provided with that in mind and
provides a convenient structure for personalizing the CL environment.
\subsection{Cursor Mode}
\ppind
Whenever an IRAF program reads the graphics or image display cursor,
the cursor lights up or starts blinking, indicating that the user should
position the cursor and type a key on the terminal to return the cursor
position, keystroke typed, and possibly a character string entered by
the user, to the calling program. The user may also read the cursor
directly, just as a program would. For example, the command
\begin{quotation}\noindent
\comptype{cl>} \usertype{$=$gcur}\\
\smallskip
\comptype{345.21 883.13 1 r}
\end{quotation}
\noindent
would read the graphics cursor, printing a cursor value string such as that
shown noting the world coordinates of the cursor, the world coordinate system
(WCS) of reference, the keystroke typed to terminate the cursor read, and
the string entered by the user if the key typed was \usertype{:} (colon).
The CL is said to be in \emphasize{cursor mode} whenever the CL is waiting
for the user to type a key to read a cursor. Cursor mode reserves the upper
case keystrokes for itself, providing all sorts of useful functions to the
user via the reserved keystrokes. For example, the graphics display can be
zoomed or panned, a hardcopy of the current screen can be made on a hardcopy
device, or the screen can be saved in or restored from a graphics metafile.
For more information on cursor mode, type \usertype{help cursors} while in
the CL.
\subsection{Background Jobs}
\ppind
The CL provides facilities for manipulating and displaying data and
allows interactive development and use of data analysis functions. However,
many fully developed image analysis scenarios are very time consuming
and need not be run interactively. IRAF allows such functions to
be developed interactively and then processed in a batch mode as
a background task, thus freeing the terminal for other interactions
once the background tasks have been started. Several
background tasks can be running at once, and these may be identical
tasks that are just operating on different data sets.
Any command, including compound commands that may involve calls to several
tasks, may be executed in the background by appending the ampersand character
`\&' to the end of the command block. The CL will create a new control
process for the background job, start it, display the job number of the
background job, and return control to the terminal.
Background job numbers are always small integers in the range 1 to n,
where n is the maximum permissible number of background jobs (typically 3-6).
\begin{quotation}\noindent
\comptype{pl>} \usertype{contour m92 dev=stdplot \&} \\
\comptype{[1]} \\
\comptype{pl>}
\end{quotation}
\noindent
If a task runs to completion, and if the CL \irafname{notify} parameter
is enabled (the default), the message
``\comptype{[n] done}'' will be printed on your
terminal when the task completes.
Jobs running in the background may use all of the commands and
perform any of the operations that interactive tasks can, but
extensive user interaction with background jobs is necessarily
somewhat limited (and not too appropriate).
Another difference is that background jobs \emphasize{do not} update
parameter \filename{.PAR} files. This is done to minimize the
confusion that could occur if a background job asynchronously
updated the parameter set for a task that was running interactively,
or vice versa. The implication of this is that parameter values that
are to be output by a task running in the background must be explicitly
written into a file if they are to be available outside that job.
Parameters passed between tasks in the same job are still processed
correctly.
If the background job writes to the standard
output, and the standard output has not been redirected, the output of
the background job will come out on your terminal mixed in with the output
from whatever else you are doing. Since this is generally not desirable, the
\filename{STDOUT} (and \filename{STDERR})
for the background job should probably be redirected to a
file and perused at a later time. The following example computes image
statistics and directs these, and any error messages, to the file
\filename{STATS.TXT}:
\begin{quotation}\noindent
\comptype{im>} \usertype{imstatistics m87 $>$\& stats.txt \&} \\
\comptype{[2]} \\
\comptype{im>}
\end{quotation}
If during the processing of a background job, the job finds it necessary to
query for a parameter, the message
\begin{quotation}\noindent
\comptype{[1] stopped waiting for parameter input }
\end{quotation}
\noindent
will appear on your terminal. It is not necessary to respond to such a
request immediately; when a convenient point is reached, respond with:
\begin{quotation}\noindent
\comptype{cl>} \usertype{service 1}
\end{quotation}
\noindent
The prompt string from the background job will be printed, just as if
you were running the job interactively. Respond to the query and the
background job will continue executing. If you do not respond to the request
for service from a background job, it will eventually time out and abort.
More control over the disposition of a batch job is possible by appending
optional arguments to the \usertype{\&} at the end of the command line,
when the job is submitted. The default action if no arguments are appended
is to run the job as a subprocess of the CL, at a priority level one less
than the CL, with output coming to the terminal unless redirected.
To run the job as a subprocess at a specific priority, a numeric string
specifying the \emphasize{host dependent} priority level may be added after
the \usertype{\&}. For example,
\begin{quotation}\noindent
\comptype{cl>} \usertype{bigjob \&4}
\end{quotation}
\noindent
will submit the job at host priority level 4. The priority level may also
be specified relative to the CL priority in a machine independent way,
e.g., \usertype{\&-1} will submit the job at a priority level one notch
down from the current CL priority (this is the default).
On systems which support batch queues (e.g., VMS) jobs may also be submitted
to a batch queue. To submit a job to a batch queue, simply add the name of
the queue after the \usertype{\&}, e.g.:
\begin{quotation}\noindent
\comptype{cl>} \usertype{bigjob \&fast}
\end{quotation}
\noindent
will submit the job to the "fast" queue. IRAF supports three logical batch
queues, the \usertype{fast} queue, for short jobs to be run at a high priority,
the \usertype{batch} queue, for medium size jobs, and the \usertype{slow}
queue, for big jobs that may run a long time. The host system name of the
desired queue may also be given. If a big job is submitted to a high priority
queue it will be killed by the system when it exceeds the maximum quota
permitted for that queue; see your system manager for more information on
the batch queues supported by your system.
Sometimes it is desirable to wait for a background job to complete before
resuming interactive work. For example, you might reach a point where
you cannot proceed until the background job has finished writing a file.
The \usertype{wait} command is used to wait for currently running
background tasks to complete.
\begin{quotation}\noindent
\comptype{cl>} \usertype{wait 1; beep}
\end{quotation}
\noindent
will halt the interactive session until background job 1 completes. Issuing
a \usertype{wait} command without a job number will cause the interactive
session to wait for \emphasize{all} background jobs to complete.
In order to discover the status of all background jobs that you
have running, the command:
\begin{quotation}\noindent
\comptype{cl>} \usertype{jobs}
\end{quotation}
\noindent
may be used. The job number will be displayed along with information
about the command that was used to start the job.
The command \usertype{spy v} may also be used. It will request the host
operating system to display the processor status (in an OS-dependent form),
including information on the status of all processes running on the system.
There are important differences in the behavior of background jobs on different
IRAF host systems. Under UNIX, the background tasks are independent of
activities that may (or may \emphasize{not}) be going on interactively.
UNIX users may terminate their IRAF session and even logoff the UNIX system
altogether, and the background jobs will continue merrily along.
In the VMS implementation of IRAF, background jobs may run either as
sub-processes or as regular VMS batch jobs in one of the system wide batch
queues. The default is to run background jobs as sub-processes, in which
case the jobs will be killed if you log out of VMS (even if you have DETACH
priviledge). Under \emphasize{both} systems, once the interactive CL session
is terminated, communication with still-running background jobs
\emphasize{cannot} be re-established, even by re-entering the CL.
\subsection{Aborting Tasks}
\ppind
Any interactive task may be aborted by typing the interrupt sequence
\key{CTRL/C}.
Control will return to the point at which the last interactive command was
entered. When an IRAF program run from the CL is interrupted, it will
usually perform some cleanup functions, deleting partially written files and
so on. If an error (or another interrupt) should occur during error recovery,
IRAF will issue the following message:
\begin{quotation}\noindent
\comptype{PANIC: Error recursion during error recovery}
\end{quotation}
\noindent
A panic abort is usually harmless, but may result in some half-written
dregs of files being left behind. A more serious problem occurs when
a subprocess becomes hung (uninterruptable). Repeatedly interrupting the
CL when this occurs will eventually cause the CL to give up and shut down,
necessitating a restart. A quicker solution might be to use the host system
facilities to forcibly kill the subprocess.
The \usertype{kill} command may be used to abort a background job. The
argument is the logical job number printed by the CL when the background
job was spawned. (It may also be a list of jobs to be killed.)
\begin{quotation}\noindent
\comptype{cl>} \usertype{kill 1} \\
\medskip
\comptype{cl>} \usertype{kill 1 3}
\end{quotation}
In systems that support batch queues as well as sub-processes,
the \usertype{kill} command may be used to control these as well.
%#########################
\newpage
\thispagestyle{empty}
\begin{center} \vspace*{1in}
\large NOTE
\end{center}
\vskip 1cm
\rm
The remainder of this document is from the original draft and has not yet
been brought up to date and may contain minor inaccuracies or omissions.
\newpage
\section{The CL as a Programming Language}
All of the examples that have been presented thus far treat the use
of the CL as a \emphasize{command language} for running existing tasks.
The CL can also be used as a high-powered desk calculator, one that
can operate on and display arrays of data as well as scalars;
and that can be fully programmed.
The following sections introduce the programming oriented functions
that are provided in the CL as background for understanding
the creation of new user tasks.
Extensive use of the CL as a programming language has not been heavily
emphasized, because there are substantial performance penalties
associated with the use of interpreted languages, especially when
dealing with large amounts of data. At the same time, the availability
of an interactive environment that allows easy exploration of
alternative analysis scenarios is very attractive, since it largely
does away with the typical development cycles of edit; compile; link;
test; edit; compile; $\ldots~$. Interactive development provides
immediate, possibly visual, feedback about the effect of the various
analytical tools upon your data.
Before delving into the details of the language however, a comment is in
order regarding the distinction made in the CL between
\irafname{command mode} and \irafname{program mode}.
\emphasize{Modes} in user interfaces are not in vogue
because of the potential source of confusion, the "How does that command
work now?" problem. IRAF is a little schizoid in this regard because of the
desire for convenient user commands on the one hand: (to minimize
the need for specific command parameter delimiters,
quotes around character strings and special handling of
file names and meta-characters); and the desire for
a familiar language syntax for programming type activities on the other.
To resolve this dilemma, the CL has two modes: \irafname{command mode} -
which is the default and is used for most terminal interactions; and
\irafname{program mode} - which is:
\begin{itemize}
\item Entered within the body of a procedure.
\item Entered within parenthesized expressions.
\item Entered on the right-hand side of an equal sign ('=').
\end{itemize}
\noindent
The syntax of the CL2 programming language was chosen to be as
compatible as possible with SPP, the portable language in which
most of IRAF is written.
Aspects of the command/program dichotomy have
already crept into the discussions of identifiers, which are treated
as character strings in command mode (\S 4.3.1), but which will be
evaluated as a parameter name if thay are enclosed in parentheses.
In the same vein, when inserted in a parenthesized expression,
an identifier that is handled as a character string
in command mode will be treated as a variable name unless it is quoted.
In program mode there is a simple disambiguating rule that can be safely
used: always quote character strings and always parenthesize expressions.
While this resolves the ambiguity it is not likely to be too popular
with most users, who typically choose a minimum entropy approach.
In the following sections, where programming issues come under
discussion, programming mode will be assumed as the default.
\subsection{Expressions in the CL}
The CL has a conventional modern expression syntax (borrowed heavily
from C and Ratfor) which should feel familiar to most
users. The following operators are provided, presented in order of
precedence:
\begin{tabular}{ll}
{\it Operator} & {\it Action} \\
$**$ & exponentiation \\
$*, /$ & the usual arithmetic operators \\
$+, -$ & and the rest of them in precedence order \\
$//$ & string concatenation \\\
\&, {\tt ||} & and, or \\
! & not \\
$<$, $<=$ & less than, less than or equals \\
$>$, $>=$ & greater than, greater than or equals \\
$!=$, $ ==$ & not equal, equal (2 equal signs)
\end{tabular}
\noindent
Parentheses may be used to alter the default order of evaluation of an
expression. Quotes are not optional in expressions or anywhere inside
parentheses; identifiers are assumed to be the names of parameters and
strings \emphasize{must} expressly be quoted using either single
or double quotes.
The data types supported by the CL
are \emphasize{boolean, integer, real, char}, and several exotic types
(\emphasize{imcur, gcur,} and \emphasize{file}) that are touched upon
later in this section. Observe that although the CL has \emphasize{no}
complex datatype, operations on complex data is supported in the rest
of the IRAF system, including the \irafname{SPP} language and
interface libraries.
Arrays of the regular data types of up to seven dimensions are supported.
Explicit type conversion is implemented with the intrinsic functions
\emphasize{int, real}, and \emphasize{str},
the last converting an argument of any data type into a string.
Mixed-mode expressions involving integers and reals are permitted,
the data type of the result is promoted to the type of the target
of the assignment operator.
The CL provides a special statement, called the \emphasize{immediate}
statement, for evaluating expressions
and printing the value at the terminal. The form of the statement
is an expression preceded by an equals sign:
\begin{quotation}\noindent
= {\it expression}
\end{quotation}
\noindent
or, if you prefer, the more conventional and more general \usertype{print}
command can be used with the same results:
\begin{quotation}\noindent
\comptype{cl>} \usertype{print (}{\it expression} [, {\it expression},
$\ldots$ ] \usertype{)}
\end{quotation}
\subsection{CL Statements and Simple Scripts}
This is not a language reference manual; nonetheless,
you will find it helpful to understand a few of the more useful
types of statements provided in the CL.
We will not attempt to present a
complete definition of the syntax of the command language,
a compendium of basic statement types is listed in the Appendix.
The preceding section introduced two statements,
the \emphasize{immediate} statement and the \emphasize{print} statement.
The \emphasize{assignment} statement should also be familiar from
previous examples.
Often we do not want simply to assign a value to a parameter,
but rather we want to increment, decrement, or scale one.
These operations can all be performed with assignment statements
in the CL, using the assignment operators \pluseq, \minuseq, \timeseq,
\diveq, and \concateq. For example, to increment the
value of a parameter, we could use the \pluseq~ assignment statement:
\begin{quotation}\noindent
\comptype{cl>} \usertype{y \pluseq {} (x $**$ 2)}
\end{quotation}
This statement increments the CL parameter \usertype{y}
by the value of the expression \usertype{(x$**$2)}. The same
operation could also be done with the next statement, but with some
small increase in typing effort.
\begin{quotation}\noindent
\comptype{cl>} \usertype{y = y $+$ (x $**$ 2)}
\end{quotation}
\noindent
The advantage of having a shorthand notation becomes obvious
when you contemplate doing arithmetic on a fully specified
parameter name as in the next examples.
\subsubsection{Assigning Values to Task Parameters}
The assignment statement may be used to set the value of a parameter
or a variable.
Most parameters are local to some task, and a ``dot'' notation may
be used to unambiguously name both the task and the parameter.
Thus, the statement:
\begin{quotation}\noindent
\comptype{cl>} \usertype{delete.verify = yes}
\end{quotation}
\noindent
may be used to set the value of the \taskname{verify} parameter
belonging to the task \taskname{delete}. Since verify is a hidden
parameter, direct assignment is the only way to permanently change
this option setting.
The task \taskname{delete} belongs to the \taskname{system} package.
Since IRAF permits several packages to be loaded at the same time,
if there happened to be another task named \taskname{delete} in the
search-path, we would have to specify the package name as well to make
the assignment unambiguous:
\begin{quotation}\noindent
\comptype{cl>} \usertype{system.delete.verify = yes}
\end{quotation}
\noindent
In the unfortunate situation of two tasks with the same name in different
packages, we would also have to specify the package name explicitly
just to be able to \emphasize{run} the task:
\begin{quotation}\noindent
\comptype{cl>} \usertype{system.delete {\it files}}
\end{quotation}
\noindent
In most cases such name collisions will not occur.
The ability to have
the same task names in more than one package has some very positive
benefits however, in that a new package of tasks that has the
same calling conventions as a standard one may be readily inserted
in the search path. This allows new algorithms to be tested without
impacting the standard system, and also provides the hooks whereby
alternate implementations of existing functions (using an array processor
for instance) can be dynamically linked into the system.
\subsubsection{Control Statements in a Script Task}
The CL provides \emphasize{if, if else, while, for, next}, and
\emphasize{break} statements for controlling the flow
of execution in a command sequence. These statements
are quite useful for writing control loops at the command
level. Other control statements (\emphasize{case, switch,} and
\emphasize{default}), which may be familiar from C or RATFOR,
are also provided to ease the programming effort.
By way of example, to print the values of the first ten powers
of two the following statements can be used:
\begin{quotation}\noindent\comptype{
cl> i=1; j=2\\
cl> while (i $<=$ 10) \{\\
>>> print (j)\\
>>> j \timeseq {} 2\\
>>> i \pluseq {} 1\\
>>> \}}
\end{quotation}
\noindent
The second of these two statements is a compound statement;
note that the prompt has changed to \comptype{>>>} to indicate this.
Consider the parenthesized argument list in the \usertype{print}
command in the above loop.
If the parameter (\usertype{j} in this example) were not enclosed in
parentheses, the CL would interpret it as a string rather than a parameter,
and would erroneously print ``\comptype{j}'' each time through the loop.
Remember that the CL will interpret identifiers as a string if found
outside parentheses, but as the name of a valid parameter or variable
inside parentheses. If the CL cannot find the identifier in its
dictionary an error message will be issued.
To avoid nasty surprises like this, one should \emphasize{always}
parenthesize argument lists in loops and within script tasks, and
make a habit of explicitly quoting items that are to be treated as
strings.
The example uses the built-in CL variables \usertype{i}
and \usertype{j}. A number of variables are provided in the CL for
interactive use; the integer variables provided with the CL
are \usertype{i,j,k}; the real variables are \usertype{x,y,z};
the string variables are \usertype{s1,s2,s3}; the booleans are
\usertype{b1,b2,b3}; and a list-structure pointer called
\usertype{list} is also provided.
The CL also has the ability to define new variables interactively;
which is discussed in section \S 6.4.
\subsection{Intrinsic and Builtin Functions}
The usual Fortran intrinsic functions
(with the exception of the hyperbolic and complex functions)
are provided in the CL, along with some others specific to IRAF.
The other intrinsic and builtin functions are those like
\usertype{set}, \usertype{if}, \usertype{while}, \usertype{case};
the data declaration and initialization statements; and the
task and I/O control statements that are described throughout
the body of this document, and are listed in Appendix A. The intrinsic
functions \emphasize{must} be used in a statement where the returned
value is explicitly assigned or output in some way.
To compute (and display) the value of \usertype{sin(x)}:
\begin{quotation}\noindent
\comptype{cl>} \usertype{= sin(x)}
\end{quotation}
\noindent
must be entered, just typing \usertype{sin(x)} by itself is an error.
The names of intrinsic functions may be used in other contexts, e.g. as
parameter names, but care is needed to avoid confusion.
\begin{tabular}{lll}
{\it Function} & {\it Action} & {\it Example} \\
abs & absolute value & z = abs(x) \\
atan2 & arctangent & r = atan2(y, x) \\
cos & cosine & x = cos(r**2) \\
exp & exponentiation & z = exp(3) \\
frac & fractional part of a number & i = frac(y) \\
int & convert input to integer & j = int(z*3) \\
log & natural logarithm of a number & x = log(z) \\
log10 & base 10 logarithm of a number & y = log10(x) \\
max & maximum value from input & x = min(1,17.4,43) \\
min & minimum value from input & y = max(47,11,92.3) \\
mod & modulus & z = mod(x, {\it base}) \\
radix & radix to any base & y = radix(x, {\it base}) \\
real & convert input to real & x = real(i) \\
sin & sine & y = sin(3*r) \\
sqrt & square root & z = sqrt(x**2 + y**2) \\
str & convert input to a string & s1 = str(num) \\
stridx & index of character in string & i = stridx(s1, 'abc') \\
substr & select substring from string & s1 = substr(s2, 3, 7) \\
tan & tangent & x = tan(2*theta)
\end{tabular}
As examples of the use of these functions, try entering the following
expressions and see if you can predict the results
(the next sections have the clues):
\begin{quotation}\noindent
\comptype{cl>} \usertype{= (sin(.5)$**$2 + cos(.5)$**$2)} \\
\smallskip
\comptype{cl>} \usertype{= 2 / 3.} \\
\smallskip
\comptype{cl>} \usertype{= (mod (int(4.9), 2) $==$ 0)} \\
\smallskip
\comptype{cl>} \usertype{= 'map' // radix (512, 8)} \\
\smallskip
\comptype{cl>} \usertype{= delete.verify}
\end{quotation}
\noindent
You may have been surprised that the result of the last example was
\comptype{no}. This is because \usertype{verify} is a boolean
parameter which can only take on the values \emphasize{yes} and
\emphasize{no}.
\irafname{CL++} \\
All of the intrinsic functions in IRAF return a value, the builtin
tasks currently do not. With the completion of changes to the CL
that are now in progress, intrinsics and builtin tasks, and any user defined
functions or tasks may return an optional value. Tasks can thus be
called either in the FORTRAN 'subroutine' style or in the 'function'
style, where a value is expected. If a task returns a value that is
not assigned to a variable it will be silently ignored.
\subsection{Defining New Variables and Parameters}
The CL provides a default set of variables that can be used for scratch
computations, and you may declare other variables as needed.
Each task that is invoked, whether it is a CL script task
or an external executable task, may have input or output parameters
associated with it, and these may be defined within the package for the
task or as part of the task itself. Data declarations
for variables contain the item name and type information,
and may also contain an optional initialization clause. Declarations
for function parameters are identical to those for variables, but they
may contain optional fields to specify prompt strings, to define a valid
data range, or to enumerate a list of valid values.
The simplest data declarations define local or global variables.
The statement:
\begin{quotation}\noindent
\comptype{cl>} \usertype{int int\_var}
\end{quotation}
\noindent
defines a simple integer variable. If this command is entered at the root
(\comptype{cl>} prompt) level, it will define a variable that is globally
accessible to any other task that is executed. When the same statement
is incorporated into the body of a script task (after the \usertype{begin}
statement), it will define a local variable visible only to that script task or
to any other task that is called by that script task. Variables declared within
the body of a package definition are globally available to all tasks
within that package, but will be removed from the set of
addressable variables when that package is unloaded.
User-defined variables may be used just like any standard IRAF
variables: in expressions, passed as parameters to
other tasks, or displayed in a variety of ways. In addition,
these variables may be initialized when they are declared:
\begin{quotation}\noindent
\comptype{cl>} \usertype{real e = 2.71828183 }
\end{quotation}
\noindent
establishes a real variable and assigns it an initial value.
This variable may be treated like a constant (as in this case)
or may be re-assigned another value during the course of computations.
The formal \taskname{parameters} for a task must be defined if the CL
is to provide any of the range checking or input prompting activities.
In the absence of a declaration, or if one is provided that
does not define these optional fields, only the name of the parameter
will be used for prompting and no range checking can be performed.
The simplest case of a \emphasize{parameter} declaration looks just like the
simple variable declaration shown above; but it must
occur within a task body \emphasize{before} the \usertype{begin} statement,
or define a parameter that is named in the calling list for a task.
The syntax of a data declaration statement is:
\begin{quotation}\noindent
\begin{tabular}{lll}
\comptype{cl>} {\it type} & [{\it = initializer} [,{\it initializer}] $\ldots$ ] \\
& \{ \\
& [{\it initializer} [,{\it initializer}] $\ldots$ ] \\
& [{\it opt\_field=value} [,{\it opt\_field=value}] $\ldots$ ] \\
& & \}
\end{tabular}
\end{quotation}
\noindent
where the valid data types for these declaration statements are shown in
the following table:
\begin{tabular}{ll}
{\it Data Type} & {\it Explanation} \\
int & integer (scalar and array) \\
real & double precision floating point (scalar and array) \\
char & character strings (scalar and array) \\
bool & boolean, yes/no (scalar and array) \\
file & file name \\
struct & special form of mutli-token string \\
gcur & graphics cursor struct \\
imcur & image cursor struct
\end{tabular}
Most of these data types should be familiar to you, but the IRAF
\irafname{struct} is a special class of data element that is used to
hold multi-token strings, mostly for input. It will be referred to again
in the section on I/O facilities in the CL (\S 6.8). \irafname{Gcur}
and \irafname{imcur} are both structs that return a multi-token result,
namely a string with RA, DEC and a data value. List structured parameters,
which are described in section \S 6.9 are typically declared as
structs.
The optional fields in a data declaration are used to define the data
ranges for checking, prompt strings, special file type information,
or a list of enumerated items.
Syntactically, the specification of these optional fields is treated
like a special form of initialization; the valid field names are
described in the following table.
\begin{tabular}{ll}
{\it Field Name} & {\it Explanation} \\
mode & auto, query, hidden processing modes \\
min & minimum value for range checking \\
max & maximum value for range checking \\
enum & enumerated list of valid responses (mutex with min/max) \\
prompt & prompt string for undefined values \\
filetype & r, rw, w, x file type specification
\end{tabular}
\noindent
All of these fields are optional, the \irafname{mode} defaults to
\irafname{auto}; \irafname{min/max} range checking defaults to NULL;
and \irafname{filetype}, which is valid only for files, defaults to
read only (\irafname{'r'}). The enumerated type (\irafname{enum}),
which names the specific responses that are acceptable, is
mutually exclusive with range checking, which defines a continuum
of values that will be accepted.
To declare an integer parameter, enable range checking for positive
values and provide a prompt string, use:
\begin{quotation}\noindent
\comptype{cl>} \usertype{int new\_parm \{ min=0, prompt='Positive integer' \} }
\end{quotation}
\noindent
and as an example of an
enumerated list of valid input values, consider:
\begin{quotation}\noindent
\comptype{cl>} \usertype{char color \{enum = 'red \pipe green \pipe blue'\} }
\end{quotation}
\noindent
which defines a default length character string that is initially undefined
and that has an enumerated list of three valid input values.
If you attempt to use the variable \usertype{color} before a value has
been assigned to it, you will be prompted for a value.
If you try to assign it a value other than one of those that
are enumerated, an error is reported.
\subsection{Declaring Array and Image Data}
Variables and task parameters may be defined as arrays of any of the
data types: int, real, char or bool. Arrays may have up to seven dimensions.
Array and image data will be referenced identically in the future,
but for now there
are some differences that are worth noting. Images are treated
as large arrays of data that are stored on disk,
and it is the amount of data to be
processed that determines the choice of storage mechanism. Images
will typically be quite bulky; it is not unusual for a single image
scene to involve five to ten megabytes of data. For this reason, image data
are most efficiently stored in disk files, and operations upon the
data are performed by buffering it into memory as needed. The
\emphasize{main difference} between an array of data and an image is that
the image will be buffered on disk.
IRAF provides a default \filename{IMDIR} directory that may be used for
bulk image file storage by all users, but it also has facilities that
manage the storing, copying, and accessing of such data sets for users who
wish to store this sort of data in their own directories.
The logical directory \filename{IMDIR} is where the IRAF system will store
your image data \emphasize{by default}. IRAF images will appear to be created
in your local user directory, but in fact it is only the \irafname{image
header file} which goes there. The bulk pixel data are
put in a second file that is part of a temporary files
system, configured and managed with large datasets in mind. Such
\irafname{pixel storage files} are transparent to the user, but if you have a
great deal of data, you may find it more efficient to set up your own directory
on a temporary files system, and to redefine \filename{IMDIR} accordingly.
If one has a personal \filename{IMDIR}, it is also convenient to save data on
tape and later restore it to disk; the header files are usually small
enough so that they need not be archived if the data is going to be restored
within a week or two.
To declare an integer array of length 100, type:
\begin{quotation}\noindent
\comptype{cl>} \usertype{int iarray[100] = 100(0)}
\end{quotation}
\noindent
which also initializes the array \usertype{iarray} to zero. A two dimensional
array with data range checking can be specified by:
\begin{quotation}\noindent
\comptype{cl>} \usertype{real rarray[50, 50] \{ min=0, max=100 \} }
\end{quotation}
\noindent
This array could be defined as an image by using the following declaration
to indicate the different \emphasize{storage class} of the data:
\begin{quotation}\noindent
\comptype{cl>} \usertype{real image rarray[50, 50] \{ min=0, max=100 \} }
\end{quotation}
\noindent
where the data in this example would be stored on disk.
The choice of whether data is to be stored
in an array which is stored entirely in memory,
or as an image on disk is up to the user.
The choice should be predicated upon the
amount of data that is to be manipulated, since speed and efficiency
of operation will be better using the image mode for data arrays
much larger than a few hundred items. At present, the
statements that manipulate these two data forms are somewhat different,
as is explained in the following section.
During the development of IRAF, the handling of images has
been a prime concern, representing as it does the major computational
and I/O load that must be accomodated. Image files currently
may be created on disk, and there are image processing functions that
know how to process this class of data. The IRAF packages
\taskname{images, imred}, and \taskname{plot} currently
handle image data.
The specification of this processing is similar, but
not identical to, the operations performed on array data.
The next section discusses use of image data and arrays within the CL.
\irafname{CL++} \\
At the present time the \irafname{IMIO and DBIO} subroutine libraries
are still undergoing design and enhancement. As a result of this effort,
the processing of image type data is not yet in final form. Existing IRAF
packages do support image processing and display
functions and these will appear to be functionally the same after the
development has been completed. The SDAS packages also support image
processing and display functions, but at this point in time the disk
format of these two types of data is vastly different,
and on this interim system, data from these two packages
cannot easily be mixed. This incompatibility is to be rectified when
the completed \irafname{IMIO and DBIO} libraries are available.
\subsection{Processing of Image Sections}
All IRAF programs which operate upon images may be used to operate on
the entire image (the default) or any section of the image.
A special notation is used to specify \irafname{image sections}. The section
notation is appended to the name of the image, much like an
array subscript is appended to an array name in a conventional programming
language. Note that array or image section \emphasize{index references}
are integer only, but that the data may be of any valid type.
\begin{quote}
\begin{tabular}{ll}
{\it section}& {\it refers to}\\
\\
pix& whole image\\
pix[]& whole image\\
pix[i,j]& the pixel value (scalar) at [i,j]\\
pix[$*$,$*$]& whole image, two dimensions\\
pix[$*$,-$*$]& flip y-axis\\
pix[$*$,$*$,b]& band B of three dimensional image\\
pix[$*$,$*$:s]& subsample in y by S\\
pix[$*$,l]& line L of image\\
pix[c,$*$]& column C of image\\
pix[i1:i2,j1:j2]& subraster of image\\
pix[i1:i2:sx,j1:j2:sy]& subraster with subsampling
\end{tabular}
\end{quote}
\noindent
In the following examples, please note that the references to image
sections are all enclosed in quotes. These are \emphasize{required}
by the present language syntax. As the note at the end of this
section indicates, this rule is to be relaxed in future.
A limited set of coordinate transformations may be specified using image
sections, but please observe that transpose is \emphasize{not} one of them.
The ``match all'' (asterisk), flip, subsample, index, and range notations
shown in the table may be combined in just about any way that makes sense.
As a simple example:
\begin{quotation}\noindent
\comptype{pl>} \usertype{graph 'pix[$*$,10]'}
\end{quotation}
\noindent
will graph line 10 of the image \usertype{pix}.
To generate a contour plot of an 800-pixel square image
subsampled by a factor of 16 in both dimensions:
\begin{quotation}\noindent
\comptype{pl>} \usertype{contour 'pix[$*$:16,$*$:16]'}
\end{quotation}
\noindent
To display the fifth $x-z$ plane of a three dimensional image named
\usertype{cube}:
\begin{quotation}\noindent
\comptype{im>} \usertype{display 'cube[$*$,5,$*$]', 1}
\end{quotation}
\noindent
on frame 1 of the image display device.
\irafname{CL++} \\
The image processing sections of IRAF are undergoing further development,
as was noted in the previous section. Currently only image data
can be processed as shown in the previous examples. Future developments
will remove the need for quoting the section specifications that identify
the image portion to be operated upon. The functional specifications
will not change substantially, nor will the syntax itself be changed
in any important way, but the need to remember to quote image section
references will be removed. Image data will continue to be
stored on disk and passed among tasks by passing the \emphasize{name}
of the file rather than passing the data itself, as a matter of efficiency.
\subsection{Array Processing in the CL}
The processing of \emphasize{array} data is handled directly in the CL,
and data arrays may also be passed to script tasks and external tasks. The
entire array will be passed, since the CL cannot yet handle passing of
sub-arrays to other tasks. The operations on arrays are handled via
implicit looping over the array expressions, and only some of the
operations described in the previous section on image data are valid
for array data. References to array data sections need not be quoted
however, and the syntax is otherwise identical to that supported for
images.
Given the declaration:
\begin{quotation}\noindent
\comptype{cl>} \usertype{real a[10], b[20], c[10,20], d[10,20,30], e[10,10]
}
\end{quotation}
\noindent
the following expressions are legal:
\begin{quotation}\noindent
\comptype{cl>} \usertype{c = 10} \hfill \#~sets~all~elements~of~c~to~10 \\
\comptype{cl>} \usertype{a = c[*,1]} \hfill \#~copies~row~1~of~c~into~a \\
\comptype{cl>} \usertype{= b} \hfill \#~prints~all~values~of~b \\
\comptype{cl>} \usertype{a = b[1:10] } \hfill \#~copies~subrange~of~b~into~a \\
\comptype{cl>} \usertype{c = d[*,*,1] }
\end{quotation}
\noindent
and the following expressions are illegal:
\begin{quotation}\noindent
\comptype{cl>} \usertype{a = c} \hfill \#~different~dimensionalities \\
\comptype{cl>} \usertype{a = c[1,*]} \hfill \#~different~limits~on~assign \\
\comptype{cl>} \usertype{a = b[11:20]} \hfill \#~different~limits
\end{quotation}
In general, for an expression to be a legal array expression in the
CL, all array references must either be completely specified
(i.e. \usertype{d[1,2,3]}), or they must loop over the same set of indices
(i.e. \usertype{a = b[1:10]}). Indices may be
specified as just the identifier (\usertype{a} or with an
asterisk as the index (\usertype{b[*]}), indicating the entire array;
or as a subrange specified by \emphasize{integer constants} separated
by a colon (\usertype{c[3:5]}).
\irafname{CL++} \\
Future developments in the CL will eliminate most of the restrictions
on array operation in the CL and will bring the syntax for operations
on images and arrays into complete alignment.
\subsection{Input and Output within the CL}
The CL provides I/O processing for parameters, cursor input and graphics
output, and controls communications to external tasks. The communications
that appear at the terminal in the form of prompts for parameters,
error messages, data range checking queries, and much of the other I/O
is performed in ASCII for portability considerations. The data items that
a user can input in response to a prompt may be:
integer values; floating point numbers, with or without exponent;
yes/no responses for boolean data; or character strings as appropriate.
Image data and other bulk data forms that are processed by the various
functions are typically \emphasize{not} passed through
the CL itself, instead the names of the files are passed about, and
temporary files are dynamically created as needed to hold intermediate
results of computations. Cursor input from graphics and image devices
are passed directly through the CL however, in order that they may be
re-directed to a file like any other I/O stream. The \irafname{imcur} and
\irafname{gcur} structs are used to handle this type of data.
As was mentioned in \S 2.4 and in the section on I/O and pipes (\S 3.3)
the CL communicates via its standard input and output,
which are ASCII streams normally connected to the terminal. The
CL functions that manipulate these streams can also be used on
data in a file, just as the CL itself can be driven with commands
from a file. The control files are all ASCII
data streams, with no implied structure, and thus are easy to construct
and to edit, should that be necessary.
The \irafname{scan} and \irafname{fscan} functions are provided
in the CL to process ASCII input streams;
the only distinction between them is that \usertype{scan} operates
on the terminal input stream (or its re-directed source) and
\usertype{fscan} specifically operates on an file. \usertype{Scan} reads
from the terminal (there is no prompt) and returns the first token it
finds in its input stream; where a token is understood to be any string
of alphanumeric characters delimited by a blank. Quotes are ignored
and no other punctuation has any special meaning. If a \key{CTRL/Z}
is entered EOF is signalled and the following
print statement will not be executed.
\begin{verbatim}
cl> if (scan (s1) != EOF)
>>> print (s1)
>>> else
>>> return
\end{verbatim}
The \usertype{print} command takes whatever is passed it as a parameter
and displays it on the terminal, so the previous example does a simple
one-line \emphasize{echo} function of input to output. The argument to
\usertype{scan} in this example is the character variable \usertype{s1},
but it could as easily be an integer:
\begin{verbatim}
cl> while (scan (i) != EOF)
>>> print ("Input was a ", i)
\end{verbatim}
\noindent
This in-line script will continue looping, reading from the input and
echoing to the output, until EOF is signalled. All valid numeric inputs
will be accepted; real input values will be truncated to integers;
character constants (single characters) will be processed as though
\usertype{int} had been called; and any invalid input values will
be silently ignored. \usertype{Print} shows another of its features,
that string constants may be directly inserted into the output stream
and that \emphasize{no format} specifications need be made.
The I/O functions can be used to process more than one data element
at a time, with no need for explicit formatting. If more data is
presented than there are identifiers in the list, the extra data
is silently ignored; and if there are more data elements in the
parameter list than there is data,
the remaining data elements retain their old values.
The output or input for these functions can be explicitly redirected,
via the usual mechanisms, or the \irafname{fscan} and \irafname{fprint}
functions can be used instead. The commands:
\begin{verbatim}
cl> list = 'infile'
cl> while (fscan (list, s1) != EOF)
>>> fprint ('junque', 'The next input line = ', s1)
\end{verbatim}
\noindent
perform exactly the same function as:
\begin{verbatim}
cl> list = 'infile'
cl> while (scan (s1, $<$list) != EOF)
>>> print ('The next input line = ', s1, $>>$ 'junque')
\end{verbatim}
\noindent
where the list structured variable \usertype{list} has been set to the
name of the file to be used for input (\filename{INFILE}) and the
output is being directed to file \filename{JUNQUE}.
These examples are hardly exhaustive, but
will serve as background information for the discussion of list
structured parameters that follows.
\subsection{List Structured Parameters}
For certain data analysis tasks, the ability to define a \emphasize{list}
of data files for batch processing can be especially useful. IRAF
supports \irafname{list structured parameters} for specifying a list
of items to be input to a function. Many, but not all, functions
will accept this form of input. List structured parameters are
associated with a file and have their own peculiar, but useful,
semantics.
Suppose we want to make a series of contour plots on the standard plotter
device of a set of data files. This can be done interactively by
entering a command to produce each plot, but this is tedious. A better
approach would be to prepare a list of image sections (see \S 6.6) to
be plotted, naming one section per line in a text file (which we choose
to call \filename{SECTIONS}). The following command could then be used
to generate the plots in the background:
\begin{verbatim}
pl> list = 'sections'
pl> while (fscan (list, s1) != EOF)
>>> contour (s1, device = 'stdplot') \&
\end{verbatim}
In this example, the assignment of \usertype{'sections'} to the
parameter \usertype{list}
has two actions, it associates the name of the file \filename{SECTIONS}
with the list structured parameter, and it causes a \emphasize{logical}
open of the file. The actual file open takes place the
first time that \usertype{fscan} is called. Successive calls to
\usertype{fscan} return successive lines from the file into the
string \usertype{s1}. When the end of file (EOF) is encountered
the \usertype{while} loop terminates. If additional calls are made to
\usertype{fscan} EOF will continue to be returned. A logical
reset to the top of the file can be performed by reassignment
of the same file name
to the parameter \usertype{list}, or another file name can be
associated with this parameter.
A user can declare other list structured data elements besides the
ones that are provided. The statement:
\begin{verbatim}
cl> struct *input = uparm\$inlist
\end{verbatim}
\noindent
declares a list structured variable named input that is bound
to the list named \filename{UPARM\$INLIST}. This file may
contain several records that define image section specifications
or the names of other files to be processed. Once the declaration is
made, lines may be scanned from the file, as in previous examples,
or the records may be fetched by use of a simple assignment operator:
\begin{quotation}\noindent
\comptype{cl>} \usertype{= input} \hfill \# displays the next record from
file \\
\comptype{cl>} \usertype{s1 = input} \hfill \# sets s1 to the next record
\end{quotation}
\noindent
Successive references to the identifier \usertype{input} will result
in successive records being read from the file it is bound to. If
an EOF is detected it is silently ignored, and the last value
read will continue to be returned. List-structured identifiers may be
integer, real, or character as well as struct type data.
The binding to a filename is the same regardless of type,
and the only difference is that data conversion is
performed on the input record to match the type of the identifier.
If you expect to write commands much more complicated than these
examples, it is time to learn about \irafname{script tasks}. This topic
is covered in \S 7 of this document and more detailed information
is given in the \reference{CL Programmer's Guide}.
\newpage
\section{Rolling Your Own}
The true power of the CL and the whole IRAF analysis
environment lies in its ability to tailor analysis functions to the
users' data. This power comes from the ability to define new
functions in the CL, and from the capability to extend the
basic IRAF system by the addition of new analysis packages.
These new routines can be developed incrementally, a line at a time,
and then defined as a new task once the function operates as desired.
User defined functions and analysis packages look just like any of the standard
functions that are provided with the system, and are called in the same way.
All of the same parameter passing, range checking, and prompting operations
of IRAF are available for user defined functions.
Beyond the ability of the CL to \emphasize{learn} the value of parameters
that you have entered, or the creation of "one-liners",
little user customization has been presented so far.
However, all of the programming and extensibility features of the CL
that have been used in the creation of the standard packages are also
available to the intrepid user, enabling the creation of a personalized
data analysis environment, one's own set of \taskname{doit} functions.
This section introduces the creation of new user script tasks,
user executable tasks, and packages of such tasks.
Examination of one of the \filename{.CL} script tasks that
defines a standard package will reveal that it
contains several \usertype{set} commands to establish
logical directory names; and then defines the set of
tasks that compose the package. Examine the script task
for the \irafname{system} package of functions:
\begin{quotation}\noindent
\comptype{cl>} \usertype{page system\$system.cl}
\end{quotation}
\noindent
to reveal the mysteries of these basic functions.
The task names that appear
in this package description contain a \irafname{logical directory}
portion (as in \usertype{system\$}) and a filename portion
(\usertype{system.cl}). The logical directory name is separated from
the rest of the file name by a dollar sign \usertype{'\$'},
as was discussed in
the section on virtual file names (\S 4.3). Use of a logical directory
specification in public packages, and even in those for your own private
use, is highly recommended, since it provides an unambiguous
specification of where to find the package and tasks.
Note that tasks need not be defined as part of a package; individual tasks
can be created and defined at any time, but a package is a convenient
way of grouping related tasks together. Many package have already been
provided in IRAF, and should be browsed by anyone who is searching
for clues about how the CL language can be used for programming.
\subsection{Creating Script Tasks}
All of the IRAF commands can be used within a
script task and will operate the same way in that environment as they
do when entered interactively. A script task need be nothing more than
a text file that contains normal CL statements or commands.
Commands may be entered in a script just as they would from a terminal
in \irafname{command mode}, or \irafname{program mode}
may be used, in which case slightly different rules apply (c.f. \S 6.0).
For simple process control scripts command mode is likely
to be satisfactory, but program mode is the obvious choice if more
complicated tasks are undertaken. The main distinction
is that task names must be entered in full and
the standard rules should be followed for variable names and character
string references. Program mode will be used in the following
examples, since it is most likely to be used in any complicated
script tasks that you might wish to develop.
In order to create a script task one has merely to invoke the editor
\begin{quotation}\noindent
\comptype{cl>} \usertype{edit {\it taskname}.cl}
\end{quotation}
\noindent
and enter the CL statements that describe the actions you wish to
have performed. When you have created the new script task
(or modified an existing one), exit the editor in the normal way,
so that the file is written in your current directory.
A script task for demo purposes might look like:
\begin{quotation}\noindent
\usertype{ \{ } \\
\usertype{ print(' Hello, world !! ') } \\
\usertype{ \} }
\end{quotation}
\noindent
In order to make this new task available to the CL, you will have to identify
it and indicate where the script task is to be found:
\begin{quotation}\noindent
\comptype{cl>} \usertype{task \$my\_new\_task = {\it taskname}.cl}
\end{quotation}
\noindent
Note that the name by which you refer to the new task
need not be the same as the name of the file, although the use of the same
name is conventional.
The `\usertype{\$}' in the \usertype{task} statement is optional and
tells IRAF not to search for a parameter (\filename{.PAR}) file for the task.
Once the task has been created and declared it may be directly invoked:
\begin{quotation}\noindent
\comptype{cl>} \usertype{my\_new\_task}
\end{quotation}
\noindent
will cause the script task file to be parsed and executed by the CL.
You may change the body of a script task
without redefining it with another \usertype{task} statement.
While tesing new script tasks, such
as this one, you may find it useful to turn on echoing:
\begin{quotation}\noindent
\comptype{cl>} \usertype{echo = yes}
\end{quotation}
\noindent
which will cause the CL to echo the commands on the terminal
as they are read from the script.
Since all of the commands that you have entered at the terminal are
logged a the history file, it is possible to edit all or part
of this command log to create a new script task. You will first have
to output part of the history log to a file and then edit it:
\begin{quotation}\noindent
\comptype{cl>} \usertype{history 30, $>$ temp } \\
\comptype{cl>} \usertype{edit temp }
\end{quotation}
\noindent
which lets you change history (not a bad trick). Once you have edited
the file, the commands needed to turn it into
a CL script task are the same as those described above.
\subsection{Passing Parameters to Script Tasks}
Parameters are used to control the operation of tasks by defining input
and output files, indicating execution options, etc. Script tasks that a user
defines may have parameters that operate in exactly the same fashion
as standard tasks.
In fact, the same prompting, learning, and limit checking mechanisms
that operate for standard tasks are available by default for user script tasks,
as well as for external user tasks (about which more in \S 7.5).
CL parameters and other variables that are defined external to a new
script task may be referenced from within the task with no special action
being taken on your part. Global variables and variables passed
from higher level tasks
are also accessible to a task. However, named parameters for the task,
or variables that are local to the task (and thus protected from
external actions), must be declared within the script task itself.
Parameters are identified by being defined
in the formal parameter list of the procedure or before the \usertype{begin}
statement, while local variables are declared only \emphasize{after}
the \usertype{begin} statement. N.B. the \usertype{begin} and
\usertype{end} statements must appear all by themselves on the line,
and anything that appears \emphasize{after} the \usertype{end} will
be ignored.
The following simple script task description will serve to illustrate
many of the salient points:
\begin{verbatim}
procedure doit (inparm, groups, region, outparm)
file inparm {prompt = 'Input file name:'}
int groups {prompt = 'Groups to process (0 for all):'}
int region[] {0, mode=hidden}
file outparm {prompt = 'Output file name:'}
begin
file cal_file = 'calib$wfpc' # Wide Field Camera
int n_group, ngp
n_group = groups # get the users group request
if (n_group == 0)
n_group = 9999
for (ngp=1; ngp <= n_groups; ngp=ngp+1) {
calib (inparm, ngp, cal_file) | # note use of pipe
clean() |
clip (region= region, >> outparm)
}
end
\end{verbatim}
\noindent
The identifiers {\tt inparm, group, region,} and {\tt outparm} are
parameters of the function and are used to pass data
into and out of the procedure proper.
There is one \emphasize{required} parameter, {\tt inparm}, which is the input
file name that contains the name of
the file to be operated upon. The other parameters are {\tt groups}
the number of data groups to be processed;
a \emphasize{hidden} parameter, {\tt region}, which will not be
prompted for; and the parameter, {\tt outparm}, which is
the name of the file that is to be written by the function. The variable
{\tt cal\_file} is local to the procedure and is only
available within the procedure body (or to any lower level routines to which
variables may be passed as parameters).
There are some subtleties here that bear mentioning. Hidden parameters,
such as {\tt region}, may be defined for script tasks and must appear
\emphasize{before} the \usertype{begin} statement, but need \emphasize{not}
appear in the formal parameter list. The {\tt groups} parameter will
be prompted for if not specified on the command line,
but is then assigned to a local variable {\tt n\_group}.
This is not required, but is desirable because of a side-effect of the
automatic prompting built into IRAF. Any query mode parameter will be
prompted for automatically, \emphasize{each time it is referenced}.
This can be very useful in a script where a new value is to be input
on each execution of a loop, but can be surprising if one only intends
to enter the value once. The obvious fix is to assign the value to
a local variable (at which time the prompt will occur) and then
operate only on the local variable.
As with the simple task described before, this procedure must be declared
with a \usertype{task} statement in order that the CL be able to locate it.
\begin{quotation}\noindent
\comptype{cl>} \usertype{task doit = home\$doit.cl}
\end{quotation}
\noindent
Remember to specify the logical
directory in the declaration so that the task can unambiguously
be located no matter which directory you use it from.
When you run this new task, you will be expected to enter a value for
the input parameters (and you will be prompted if you don't).
Remember that once you
have used the \usertype{task} statement to inform the CL how to find your
new function, you need not do so again during that session, since the original
declaration of the task will allow it to be located even if you edit the body
of the task to change its internal operation.
If you need to change the number or type of parameters to a task,
or to change the name of a task, move it to another directory,
or if you wish to redefine the meaning of one of the standard tasks
in the system, you will have to use the \usertype{redefine} command.
The following commands:
\begin{quotation}\noindent
\comptype{cl>} \usertype{rename home\$doit.cl funcs\$doit.cl} \\
\comptype{cl>} \usertype{redef doit=funcs\$doit.cl}
\end{quotation}
\noindent
rename the file \filename{HOME\$DOIT.CL} to \filename{FUNCS\$DOIT.CL}
and then redefines the \taskname{doit} task to point to the script.
This redefinition causes the CL to reprocess the script task
in order to re-establish pointers to the file and to
redefine the data declarations.
Once you have tested your new task and have it
debugged, you may wish to enter a \usertype{task} definition for
it into your \filename{LOGIN.CL} file, or to install it in your own
package of private functions.
\subsection{Using List Structured Parameters in a Script Task}
It is possible to define a CL script task such that a sequence of files
whose names are defined in an input list
may be processed in one call to the task. This is convenient
when a number of files need to be processed in an identical way. The
following example shows how the task \usertype{doit\_toit} has been
setup to accept a list structured input parameter, and then
to call another task, passing the files from the list one at a time
to the other task. The obvious advantage is that the development
of the task that really does the work, viz. \usertype{doit}, can be done in
isolation from the mechanics of batch processing the list of data files.
The \usertype{doit\_toit} function is set up for production use and,
as such, it logs all activity in the standard logfile.
It may be run as a background task, like any other IRAF function.
\begin{verbatim}
# DOIT_TOIT -- A driver task for batch operation of DOIT.
procedure doit_toit (images, section)
file *images { prompt = 'List of images to be changed' }
char section { prompt = 'Section of input images to be output' }
begin
struct imgs # working storage for image file name
bool klog # default size is 32 chars
file logf
klog = keeplog # get global keeplog flag
logf = logfile # ditto the log file name
while (fscan (images, imgs) != EOF) {
if (klog) {
# Output a startup message if keeplog is true.
print (' DOIT_TOIT: Process images ', >>logf)
time (>> logfile)
print (' Images : ', imgs, >>logf)
print (' Section : ', section, >>logf)
}
# Do the actual task by calling the DOIT function, passing
# in the file name with the section concatenated.
doit (imgs // section, imgs)
if (klog) { # output the trailing message
time (>>logf)
print (' DOIT_TOIT: Completed. ', >>logf)
}
}
end
\end{verbatim}
\noindent
The declaration for the variable \usertype{images} needs
some explanation. The asterisk \usertype{'*'} indicates that
\usertype{images} is a \irafname{list structured parameter}, i.e. that
it is to be processed as a pointer to a parameter list, rather than
as the parameter itself. In this instance it will contain the name
of a file that itself contains a list of the names of files to be
processed.
As with the other script tasks that have been described, this one must
be declared to the CL via a \usertype{task} statement before it can
be executed. Once this has been done the task can be called as follows:
\begin{quotation}\noindent
\comptype{cl>} \usertype{task doit\_toit = home\$doit\_toit.cl} \\
\comptype{cl>} \usertype{doit\_toit ( 'images.txt', '[]' )}
\hfill \#~no~sub-sections \\
\comptype{cl>} \usertype{tail logfile} \hfill \#~check~the~logfile~messages
\end{quotation}
\noindent
The name of the file containing the list of images \filename{``IMAGES.TXT''}
is passed directly into the task as a quoted string.
\subsection{Establishing Your Own Function Package}
Once you have defined several functions that do a useful set of operations,
you may wish to set them up so that they are always available to you.
This can be done by defining them as a package, which is the mechanism
that IRAF uses to organize the other groups of tasks that are made
available as part of the system proper. (Or, more easily, by putting
the \usertype{task} declarations into your \filename{LOGIN.CL} file.)
\newpage
\begin{verbatim}
package my_package
set funcs = "home$func/" # define the logical directory
task fib = funcs$fibonacci.cl
glib = funcs$wordy.cl
doit = funcs$doit.cl
clbye() # invoke the cl again for interactive use
\end{verbatim}
\noindent
If you now place the declaration for this package task in your
\filename{LOGIN.CL} file, these tasks will be available to you whenever
you login to IRAF. It is a good practice to always use logical directory
names in task declarations and in other file names, since changing the
search path with a \usertype{chdir} may otherwise render tasks not
locatable.
Packages may, of course, be more complex than the above, since they can
refer to several logical tasks that may be CL script tasks or executable
tasks. User packages may also reference logical tasks that are in other
packages directly, if only one or two such tasks from another package are
needed. Additionally, a package task may declare variables
that are to be treated as global to all of the tasks \emphasize{within}
the package, but are to remain local to the package itself. Other IRAF
commands can be included in a package task as well, such as a load request
for a package of utility routines. As you will recall, the
load operation for a package is implicitly executed whenever a package
is named; thus, a utility package such as \taskname{plot} or \taskname{imred}
can be loaded and made available just by naming it in the package description.
\subsection{Creating Fortran, SPP and other External Tasks}
While the IRAF and SDAS applications packages, along with the CL
language, offer substantial facilities for interaction with and
analysis of data, it would not be unusual for users to wish to
make their existing algorithms available
for use in IRAF. Neither the IRAF packages nor the SDAS packages
can provide all of the functions that everyone might desire. IRAF has been
developed as an \emphasize{open system}, and is therefore extendible by the
user so that externally compiled programs are accessible with the CL.
These programs may be coded in any language that
conforms to the standard calling conventions, but Fortran, C, and the
Subset PreProcessor (SPP, the IRAF portable language) have predefined sets of
interface routines that establish access to the IRAF \irafname{kernel}
functions.
It is suggested that the Fortran programmer use the SDAS/ST
interface routines to access the IRAF environment. These routines
provide access to parameters, perform I/O on image files as well as other data
file formats, provide facilities for header data manipulation, etc.
The routines are described in the \reference{SDAS Applications Programmer's
Guide} (the \reference{Green Book}) and in the \reference{Software
Interface Definition, ST-ECF O-11}, which describes the set of
interfaces that have been agreed upon between the STScI and the
European Coordinating Facility (ECF).
The SDAS interface routines (and the ST-ECF interfaces) are all
built upon the existing IRAF kernel interfaces as described in the
\reference{IRAF Programmer's Crib Sheet}. These interfaces are rather
more complete than the SDAS/ST ones, providing full access to the facilities
of the IRAF virtual operating system. These routines can be called directly
from SPP, but typically \emphasize{cannot} be called directly from
Fortran programs.
A selection of software development tools are available to the user who wishes
to integrate personal programs into the IRAF environment. These utilities
are provided as parts of the \taskname{softools} package, and include such
functions as IRAF-specialized compilation and linkage, help file creation, etc.
A simple SPP language routine is included here as an example that
can be tried from the terminal. It is not a particularly useful
function (it just feeps the terminal bell), but does show the
ease with which an external task can be linked into the environment.
\begin{verbatim}
#------------------------------------------------------------
# Simple task to show use of SPP external procs
# Compile and link using SPP command in Softools
task feep = t_feep
include <chars.h> # include the standard char defs
# FEEP -- Feep the terminal.
procedure t_feep()
begin
call putc (STDOUT, BEL)
end
\end{verbatim}
\noindent
After you have used the editor to create the program source file,
you should load the \irafname{softools} package that contains
the \irafname{xc} compile/link tool. This will compile the
program, link it, and create an executable named \filename{FEEP.E}.
\begin{quotation}\noindent
\comptype{cl>} \usertype{softool} \\
\comptype{so>} \usertype{xc feep.x}
\end{quotation}
Once the \usertype{feep} task has been compiled and linked
it may be made available from within the IRAF environment
in a fashion analogous to that used for CL script tasks.
A \usertype{task} statement that names the executable file and binds it
to a task name must be used to declare the task to the CL. Once this
has been done, the executable task can be invoked just like any other
task.
\begin{quotation}\noindent
\comptype{cl>} \usertype{task feep = feep.e } \\
\comptype{cl>} \usertype{feep} \hfill \#~is~used~to~call~it
\end{quotation}
\noindent
N.B. IRAF tasks written in SPP (and other languages)
may contain more than one logical task, and the CL
\usertype{task} statement must be used to declare each of them.
The logical task names used on the CL \usertype{task} statement
\emphasize{must} correspond with the task names from the {\tt task}
statement used in the body of the SPP file.
The parameter handling facilities at the user level behave
identically for executable
external tasks and for CL script tasks. If the complete facilities
of parameter range checking, prompt messages, and default values
are desired, a data declaration statement that defines
these values will have to be specified. If a declaration statement
is not provided, the standard prompt processing (naming the
parameter and soliciting input) will be used when parameters are
referenced.
The details of parameter and file I/O in SPP, and in the Fortran and
C interfaces, are sufficiently different from those presented for the
CL that the entire subject is best deferred to a separate document.
It is important to note however, that the facilities that are available
in the CL and in the IRAF kernel routines that support it are
equally available to all executable modules. The implication of
this is that any program that has been linked into IRAF will have the
same apparent interface as all of the existing programs, and thus
can easily be made to appear as a unified part of the larger system.
This can, of course, be subverted, and programs may maintain their
own identities in so far as that is desirable. However, the advantages
of a unified user interface and of a well defined and completely
implemented set of flexible interface routines cannot be stressed enough.
\newpage
\section{Relevant Documentation (the Yellow Pages)}
This document should serve to get the first-time user started (and if it
doesn't, we would like to know about it), but there are many topics
that have been covered quickly or not at all. Other documents and
sources of information about IRAF, SDAS, standard packages, use of
SPP, IRAF internals, etc. exist and this section will provide pointers
into that realm for those who would like more information on these topics.
\subsection{IRAF Command Language}
Some of the documents describing the CL are now somewhat out of date
since there have been at least two revisions to IRAF since they were
written. However, these documents are readable and are still
useful, since, by design, most of the changes made to the CL are
compatible with what had gone before.
\noindent
\reference{CL Programmer's Guide, in preparation}
This is to be the most complete introduction to programming in the
CL and to the facilities of the CL. As such, it provides details of language
use (especially helpful when developing external and/or script tasks in
Fortran, SPP, and C). Also included are descriptions of the workings of
the CL, the IRAF kernel and inter-process communications as they affect
the use of IRAF for program development.
\noindent
\reference{Detailed Specifications of the IRAF Command Language, rev Jun82}
This paper discusses in technical detail the major functions of the CL
and some details about how it works. Since this is a specifications
document, it is not as readable as a user document, but it
does cover many of the same areas as the \reference{CL Programmer's Guide}
in somewhat more detail.
\subsection{IRAF Applications Packages}
Much of the richness of the IRAF environment comes from the packages
of applications programs that are being made available within the
environment. The IRAF group at NOAO and the SDAS group at STScI have been
developing analysis programs that are available as packages
within the IRAF environment, and the end-user-oriented documentation of
these systems is described below.
\noindent
\reference{IRAF Applications Packages, Structure and Requirements, Aug83}
This document is an attempt to define fully the decomposition of the IRAF
system and applications software into packages. The functions performed by
each package are summarized in the form of requirements.
Descriptions of specific IRAF applications packages developed at Kitt Peak
are available in a set of user-handbooks :
\begin{itemize}
\item \reference{APPHOT - Digital Aperture Photometry, Aug83}
\item \reference{GRAPH - Simple Graphics Routine, Mar84}
\item \reference{SURFACE - 3-D Surface Display, Mar84}
\item \reference{CONTOUR - Contour Map Display, Mar84}
\item \reference{HELP - On-Line HELP for IRAF, Mar84}
\item \reference{DATAIO - Data Readers and Writers, Mar84}
\item \reference{LISTS - Basic List Processing Functions (ASCII files), Mar84}
\item \reference{UTILITIES - Miscellaneous Utility Functions, Mar84}
\item \reference{SOFTOOLS - Software Utilities, make, yacc, xc, mklib, Mar84}
\end{itemize}
\noindent
\reference{Science Data Analysis Software Requirements, Final, Aug82}
These are the contract requirements of the SDAS system.
\noindent
\reference{SDAS User's Manual, in preparation}
A descriptive guide to the use of SDAS.
\subsection{Standard Program Interfaces}
There are three sets of interface routines available to the programmer:
those for SPP, those for C, and those for Fortran. The language that
you use depends on the nature of the project being undertaken, your
own level of expertise, and on the
need for creating portable code. SPP is the language of choice for packages
that are to become part of IRAF or for tasks that require access to the
entire virtual system interface. Fortran and the SDAS/ST
interfaces will remain the choice for existing Fortran codes and for many
small scientific applications programs. Users are encouraged to choose
the SDAS/ST interface for their Fortran programs. C has been used
for the innards of the CL itself, and a set of interfaces (the LIBC library)
is provided that emulates the UNIX standard I/O facilities and
gives access to the IRAF kernel facilities.
\noindent
\reference{A Reference Manual for the IRAF System Interface, rev May84}
This document is the most complete (and recent) treatment of the
linkages between the portable IRAF kernel, the CL, the external procedures
and the system dependent Z-routine layer. It describes these interfaces
in detail and has the complete specifications of the
Z-routine interfaces. It is of particular use to both the individual who is
trying to port IRAF to another system (it is a \emphasize{must read} for such
persons) and to the system or applications
programmer who wants a more detailed understanding of IRAF.
\subsubsection{SPP Interfaces}
\noindent
\reference{Programmer's Crib Sheet for the IRAF Program Interface, rev Sep83}
This document describes the complete set of interface functions
for the IRAF virtual
operating system as it is available to the SPP programmer. Several
sets of library functions are described for accessing images and various
kinds of data files, terminal capabilities, graphics and image I/O, etc.
Programs written using only these interfaces
will be fully portable, along with the main body of IRAF code.
\noindent
\reference{Reference Manual for the IRAF SPP, rev Sep83}
This is the definitive document about the IRAF Subset Preprocessor
language. The language is somewhat like Ratfor (from which
it derives), but it has extensions for dealing with the memory management
and referencing issues that arise when operating on large scale image data.
\noindent
\reference{The Role of the Preprocessor, rev Dec81}
This document is an early discussion of the philosophy behind use of
the SPP language. As such, it is valuable
background reading for anyone who wishes to understand fully the
benefits of using a preprocessed language for
implementing a large body of portable
code like IRAF.
\subsubsection{Fortran Interfaces}
\noindent
\reference{SDAS Applications Programmer's Guide}
This is the complete description of the interface set that is now
being used to develop the SDAS program suite at STScI. These interfaces
are expected to be replaced eventually by the set of SDAS/ST
interfaces mentioned in the following document.
\noindent
\reference{Software Interface Definition, ST-ECF O-11, rev Aug84}
This describes the set of standard interfaces agreed upon between
the STScI and the ST-ECF. It incorporates most of the features of the
SDAS standard interfaces and is to be used for program development
at STScI and for future MIDAS programs developed at ESO. It is
a rather complete interface for image data, process parameters,
and table data structures, but does leave out many of the other
facilities provided in the complete IRAF SPP interface.
\newpage
\section{And into the Future}
This version of IRAF and its CL represents the first external release
of a system that has been under development for more than three years,
and which will continue to evolve for several
more. IRAF was born out of the need for a system that
could survive changes in operating systems and hardware, since such
changes are a normal part of computer system evolution. To
accomodate such changes, and to provide a level of stability
and portability across operating systems,
IRAF is a \emphasize{layered} system: the CL is the user layer;
the kernel is the operating system independent layer; and the
z-routines are the system dependent layer.
Most of the discussion in this document describes the appearance
and function of the current command language (CL2), the user layer
of IRAF. As has been noted at various points in the text,
the CL is still undergoing
development and is expected to change over time. (The paragraphs
marked \irafname{CL++} in the text hold the clues.) The intent
in these changes is two-fold:
\begin{itemize}
\item Provide evolutionary enhancements to the user interface
to improve utility, functionality, usability and coherence.
\item Bring the programming elements of the CL language
into line with the SPP language which is used for the bulk of the
IRAF portable code.
\end{itemize}
\noindent
These requirements are somewhat at odds, as was noted in \S 6, but
further attention is being given these issues to try and resolve
the dilemma. Although not all elements of the CL language can
be mapped easily into the SPP programming language (consider the I/O
control commands), the notion that one
can do development in an interactive environment and then
realize compiled code speeds for execution is an attractive one.
The CL2 implementation has
taken steps in this direction and we expect to see how far this idea
can be taken over the next few years.
\subsection{Near-Term Software Projects}
While the evolution of the CL is an important part of IRAF, there
are other elements of the system that are even more important which are
still under development at this time. The most important single area
for development is the database and data catalogue.
Design and prototyping of these important functions, and the
necessary query language, is in progress
right now. These functions are doubly important, since they both represent
a user facility for creating and operating on private catalogues
of data; and also are at the heart of the effort to merge the
SDAS functions cleanly into the IRAF control structure. Only after
the DBIO and IMIO packages have been fully implemented and integrated
into the rest of the system will functions from these two large
applications groups be able to share data and file structures.
A tables system is also envisioned that will offer similar capabilities
to the MIDAS tables, but will be built upon the DBIO routines.
The areas of graphics and image display will also receive
attention during the next year. The current GIO package
supports a fast kernel and both a GKS and an NCAR emulation.
However, image data are not merged into this structure
and no common meta-file
formats exist that allow image, annotation, and overlay graphics
to be represented in one consistent form. Some efforts have already
been made toward understanding what needs to be done and how (or if)
the requirements can be satisfied within existing standards.
Further efforts will be made, both at NOAO and STScI, and at
other facilities like RAL who have expertise in this area, to develop
an approach that satisfies the requirements.
Developments in the area of networks, both LAN and wide-area; workstations;
and the related topics of access to distributed data bases and archives
are also receiving attention. We believe that IRAF
has a sufficiently robust and flexible structure that it can operate
successfully within a distributed operating environment. Small scale
efforts are now underway to explore some of the issues related to network
file systems.
At the same time, a prototype project is underway with a
single platter laser disk, to evaluate the suitability of this media
for large scale, long term archival storage of images and other related
data. As a part of this activity, IRAF is currently
being ported to a SUN workstation and high resolution image display
at the STScI. IRAF and its database package will be important
to this effort, since they will provide some of the basic facilities
for processing the data and managing the catalogues for this archive.
These are all components of a distributed data system, a long range goal
for the Space Telescope community, and probably of interest to the entire
astronomy and astrophysics community. To the extent that IRAF proves
useful to astronomers, it will play a key role in such a data system.
\subsection{Where Is the Future?}
The usual rapid pace of developments in hardware and software systems
will also prompt consideration of changes to the external appearance
and some of the internal implementation details of IRAF.
Developments in graphics and image displays, and in various data
input and storage
devices promise to make revolutionary changes in the way that
people and computers interact. High resolution graphics, touch screens,
mice, WYSIWYG (What You See Is What You Get), DWIM (Do What I Mean),
and the 'cluttered desk' paradigm pioneered by Xerox PARC and emulated
by everyone else, will all appear in one form or another in a variety
of different systems in the next few years. These presentation
techniques and differing interactive views of data,
when well thought out and integrated into a system,
can serve to make computers more accessible to people.
These ideas, however, have been much slower to arrive in the
large-scale systems that have been used for data analysis than in
the super-micro and PC class machines.
IRAF, in its current version, incorporates only some of these elements,
but many others will be experimented with as it is ported to
different hardware environments.
Because the CL is a separable piece of the system,
it can be changed or replaced, without necessarily making major changes
to the underlying system structure. Efforts now underway to move
IRAF out of the super-mini systems where it has been developed, and
into super-micro workstations will afford the opportunity to
explore some of these user interface issues in a prototyping
mode. Depending on the results of such experiments,
other CL interfaces that take advantage of those
elements that prove successful are likely to evolve.
These statements should not be
construed to mean that constant change will be the norm. IRAF
was designed to protect the substantial software investment that any
large data analysis system represents, and this it will do, both for
the developers and for the users. The IRAF kernel and the layered
interfaces for applications programs are quite stable, and are not
expected to change, except to incorporate additional functionality.
Furthermore, any changes proposed for
the user interface will be carefully evaluated in terms of their
impact on the existing user community. But, just as we expect that
faster, more efficient FFT or filtering algorithms would receive
a welcome reception we expect that a stable, but slowly evolving system
that continues to serve
users needs will meet with approval. Feedback and commentary from the
users of the system will be vitally important in this development
process, and we encourage that dialogue.
\newpage
\appendix
\section{Appendices}
\subsection{CL Commands and the System Package}
\subsubsection{CL Intrinsic and Builtin Functions}
\begin{tabular}{rcl}
access & - & Test to see if a file exists \\
bye & - & Exit a task or package \\
cache & - & Cache parameter files, OR \\
& & Print the current cache list (no arguments)\\
cd & - & Change directory \\
chdir & - & Change directory \\
cl & - & Execute commands from the standard input \\
clbye & - & Exit a task or package to save file descriptors \\
defpac & - & Test to see if a package is defined \\
defpar & - & Test to see if a parameter is defined \\
deftask & - & Test to see if a task is defined \\
ehistory & - & Edit commands from the history log file \\
envget & - & Get the string value of an environment variable \\
eparam & - & Edit the parameters for a function \\
error & - & Print error code and message and abort \\
flprcache & - & Flush the process cache \\
fprint & - & Format and print a line into a parameter \\
fscan & - & Scan and format an input list \\
hidetask & - & Define a new hidden task \\
history & - & Print the last few commands entered \\
jobs & - & Show status of background jobs \\
keep & - & Make recent set, task, etc. declarations permanent \\
kill & - & Kill a background job or detached task \\
logout & - & Log out of the CL \\
lparam & - & List the parameters of a task \\
mktemp & - & Make a temporary (unique) file name \\
mkdir & - & Make a new file sub-directory \\
package & - & Define a new package, OR\\
& & Print the current package names (no arguments) \\
print & - & Format and print a line on the standard output \\
radix & - & Print a number in the given radix \\
redefine & - & Redefine a task \\
scan & - & Scan and format the standard input \\
service & - & Service a query from a background job \\
set & - & Set an environment variable, OR \\
& & Print environment (no arguments) \\
show & - & Show the values of one or more environment variables \\
sleep & - & Pause execution for specified period \\
substr & - & Extract a substring from a string \\
task & - & Define a new task \\
unlearn & - & Restore the default parameters for a task or package \\
update & - & Update a task's parameters (flush to disk) \\
version & - & Print the revision date of the CL \\
wait & - & Wait for all background jobs to complete
\end{tabular}
\subsubsection{System Package Functions}
\begin{tabular}{rcl}
allocate & - & Allocate a device \\
beep & - & Beep the terminal \\
clear & - & Clear the terminal screen \\
concatenate & - & Concatenate a list of files to the standard output \\
copy & - & Copy a file, or copy a list of files to a directory \\
count & - & Count the number of lines, words, and characters in a file \\
deallocate & - & Deallocate a previously allocated device \\
delete & - & Delete a file \\
devstatus & - & Print the status of a device \\
directory & - & List files in a directory \\
diskspace & - & Show how much diskspace is available \\
edit & - & Edit a file \\
files & - & Expand a file template into a list of files \\
gripes & - & Post bug reports, complaints, suggestions \\
head & - & Print the first few lines of a file \\
help & - & Print online documentation \\
lprint & - & Print a file on the line printer device \\
match & - & Print all lines in a file that match a pattern \\
news & - & Page through the system news file \\
page & - & Page through a file \\
pathnames & - & Expand a file template into a list of OS pathnames \\
protect & - & Protect a file from deletion \\
rename & - & Rename a file \\
revisions & - & Print/post a revision notice for a package \\
rewind & - & Rewind a device \\
sort & - & Sort a text file \\
spy & - & Show processor status \\
stty & - & Show/set terminal characteristics \\
tail & - & Print the last few lines of a file \\
tee & - & Tee the standard output into a file \\
time & - & Print the current time and date \\
type & - & Type a file on the standard output \\
unprotect & - & Remove delete protection from a file
\end{tabular}
\clearpage
\subsection{SDAS Analysis Packages}
\begin{itemize}
\item General Data Analysis \\
\begin{tabular}{rcl}
areavolum & - & Integrate to find the area/volume under a curve/surface\\
arrayops & - & Perform arithmetic, logical, and matrix operations on\\
& & \quad SDAS data arrays\\
convert & - & Convert data from one type to another (real, integer,\\
& & \quad logical, byte)\\
curfit & - & Fit curve to one-dimensional data\\
dimage & - & General image display package\\
extract & - & Extract a subset of a data array\\
fitsrd & - & Read a standard FITS tape and create an SDAS disk data file\\
fitswr & - & Write a standard FITS tape from an SDAS disk data file\\
four1d & - & Perform one-dimensional Fourier analysis\\
four2d & - & Perform two-dimensional Fourier analysis\\
hstats & - & Compute standard statistics, including histograms\\
locate & - & Locate features in a spectrum, time series, or image\\
makemask & - & Make a data mask\\
plot1d & - & Plot one-dimensional (equally-spaced) data\\
plot2d & - & Plot two-dimensional (equally-spaced) data as contour\\
& & \quad map or ruled-surface map\\
probdist & - & Compute standard probability distributions\\
register & - & Compute registration parameters for two displaced data\\
& & \quad arrays (use in conjunction with resample)\\
repmod & - & Replace/modify/input data in an existing data array\\
resample & - & Resample data from one grid to another (shift, rescale, rotate)\\
smooth & - & Smooth data by convolution filtering, median window
\end{tabular}
\item Spectral Analysis \\
\begin{tabular}{rcl}
cntana & - & Continuum analysis (determine reddening, correct for\\
& & \quad reddening, fit continuum models)\\
ewlnst & - & Measure equivalent width/line strength\\
gspect & - & Generate a spectrum for testing\\
rvdet & - & Measure radial velocities\\
specph & - & Spectrophotometry
\end{tabular}
\item Image Analysis \\
\begin{tabular}{rcl}
gimage & - & Generate an image for testing\\
\end{tabular}
\clearpage
\item Time Series Analysis \\
\begin{tabular}{rcl}
glcurv & - & Generate a light curve for testing\\
hldelc$^*$ & - & Correct HSP times for light delay time\\
hspcir$^*$ & - & Correct HSP data for instrumental response\\
hspolar$^*$ & - & Polarimetry package for HSP data\\
hspphot$^*$ & - & Photometry package for HSP data\\
hsubbkg$^*$ & - & Subtract background from HSP data
\end{tabular}
\item Astrometric Analysis \\
\begin{tabular}{rcl}
bdresid$^*$ & - & Make histogram of FGS beam deflector residuals\\
centroid$^*$ & - & Centroid raw FGS encoder data\\
errsig$^*$ & - & Make histogram of FGS error signals
\end{tabular}
\end{itemize}
\vskip 2cm \noindent
$*$ --- these programs may not be available
\clearpage
\subsection{IRAF Application Packages}
\begin{itemize}
\item CRYOMAP Package \\
\begin{tabular}{rcl}
extract & - & Extract Cryomap spectra\\
findspectra & - & Find Cryomap spectra\\
iids & - & Convert integrated spectra extractions to IIDS format\\
maplist & - & List information about the multi-aperture plate\\
specplot & - & Plot extracted integrated spectra
\end{tabular}
\item DATAIO Package \\
\begin{tabular}{rcl}
bintxt & - & Convert a binary file to an IRAF text file\\
ldumpf & - & List the permanent files on a Cyber DUMPF tape\\
mtexamine & - & Examine the structure of a magnetic tape\\
rcamera & - & Convert a Forth/Camera image into an IRAF image\\
rcardimage & - & Convert a cardimage file into a text file\\
rdumpf & - & Convert IPPS rasters from a DUMPF tape to IRAF images\\
reblock & - & Copy a binary file, optionally reblocking\\
rfits & - & Convert a FITS image into an IRAF image\\
ridsfile & - & Convert IDSFILES from a DUMPF tape to IRAF images\\
ridsmtn & - & Convert mountain format IDS/IRS data to IRAF images\\
ridsout & - & Convert a text file in IDSOUT format to IRAF images\\
rpds & - & Convert a PDS image into an IRAF image\\
rrcopy & - & Convert IPPS rasters from an RCOPY tape to IRAF images\\
txtbin & - & Convert an IRAF text file to a binary file\\
wcardimage & - & Convert text files to cardimage files\\
wfits & - & Convert an IRAF image into a FITS image\\
widsout & - & Convert an IRAF image to IDSOUT text format
\end{tabular}
\item ECHELLE Package \\
\begin{tabular}{rcl}
background & - & Subtract a scattered light background\\
extract & - & Extract Echelle orders\\
findorders & - & Find Echelle orders\\
iids & - & Convert integrated spectra extractions to IIDS format\\
orderplot & - & Plot extracted integrated spectra
\end{tabular}
\clearpage
\item GENERIC Package \\
\begin{tabular}{rcl}
biassub & - & Subtract a bias image\\
chimages & - & Change images: trim, flip, transpose, rotate\\
colbckgrnd & - & Fit and subtract a column by column background\\
colflat & - & Create a flat field by fitting a function \\
&& to the image columns\\
darksub & - & Scale and subtract a dark count image\\
dcbias & - & Subtract a constant bias and trim images\\
flatten & - & Flatten images using a flat field\\
linebckgrnd & - & Fit and subtract a line by line background\\
lineflat & - & Create a flat field by fitting a function \\
&& to the image lines\\
normalize & - & Normalize images\\
normflat & - & Create a flat field by normalizing and \\
&& replacing low values
\end{tabular}
\item IMAGES Package \\
\begin{tabular}{rcl}
imarith & - & Simple image arithmetic\\
imaverage & - & Average images together\\
imcopy & - & Copy an image\\
imdelete & - & Delete an image\\
imlinefit & - & Fit a function to each image line\\
imheader & - & Print an image header\\
imhistogram & - & Compute image histogram\\
imstatistics & - & Compute and print image statistics\\
imtranspose & - & Transpose a two dimensional image\\
listpixels & - & Convert an image section into a list of pixels\\
sections & - & Expand an image template on the standard output\\
shiftlines & - & Shift image lines\\
tv & - & Image display (see TV-IMAGE Package)
\end{tabular}
\item LISTS Package \\
\begin{tabular}{rcl}
average & - & Compute the mean and standard deviation of a list\\
gcursor & - & Read the graphics cursor\\
imcursor & - & Read the image display cursor\\
table & - & Format a list of words into a table\\
tokens & - & Break a file up into a stream of tokens\\
unique & - & Delete redundant elements from a list\\
words & - & Break a file up into a stream of words
\end{tabular}
\clearpage
\item LOCAL Package \\
\begin{tabular}{rcl}
binpairs & - & Bin pairs of (x,y) points in log separation\\
epix & - & Edit pixels in an image\\
fields & - & Extract specified fields from a list\\
imreplace & - & Replace pixels in a range by a constant\\
imscale & - & Scale an image to a specified (windowed) mean\\
imstack & - & Stack images into an image of higher dimension\\
imsurfit & - & Fit a surface to an image\\
imtitle & - & Change the title of an image\\
notes & - & Record notes\\
polyfit & - & Fit polynomial to lists of X,Y pairs
\end{tabular}
\item MULTISPEC Package \\
\begin{tabular}{rcl}
findpeaks & - & Find the peaks\\
fitfunction & - & Fit a function to the spectra parameter values\\
fitgauss5 & - & Fit spectra profiles with five parameter \\
&& Gaussian model\\
modellist & - & List data and model pixel values\\
msextract & - & Extract spectra\\
mslist & - & List entries in a MULTISPEC database\\
msplot & - & Plot a line of image and model data\\
msset & - & Set entries in a MULTISPEC database\\
newextraction & - & Create a new MULTISPEC extraction database\\
newimage & - & Create a new multi-spectra image
\end{tabular}
\item PLOT Package \\
\begin{tabular}{rcl}
contour & - & Make a contour plot of an image\\
graph & - & Graph one or more image sections or lists\\
pcol & - & Plot a column of an image\\
pcols & - & Plot the average of a range of image columns\\
prow & - & Plot a line (row) of an image\\
prows & - & Plot the average of a range of image lines\\
surface & - & Make a surface plot of an image
\end{tabular}
\clearpage
\item SOFTOOLS Package \\
\begin{tabular}{rcl}
hdbexamine & - & Examine a help database\\
lroff & - & Lroff (line-roff) text formatter\\
make & - & Table driven utility for maintaining programs\\
mkhelpdb & - & Make (compile) a help database\\
mklib & - & Make or update an object library\\
mkmanpage & - & Make a manual page\\
xcompile & - & Compile and/or link an SPP, C or Fortran program\\
yacc & - & Build an SPP language parser
\end{tabular}
\item TV-IMAGE Package \\
\begin{tabular}{rcl}
blink & - & Blink the TV display\\
display & - & Manipulate the TV display\\
erase & - & Erase the TV display\\
frame & - & Define the frames to be manipulated\\
lumatch & - & Match color look up tables\\
monochrome& - & Set display into monochrome mode\\
pseudocolor& - & Set pseudocolor mode on display\\
rgb & - & Set true RGB mode on display\\
window & - & Define a display window area\\
zoom & - & Zoom the display
\end{tabular}
\item UTILITIES Package \\
\begin{tabular}{rcl}
airmass & - & Compute the airmass at a given elevation \\
&& above the horizon\\
ccdtime & - & Compute time required to a observe star \\
&& of given magnitude\\
detab & - & Replace tabs with tabs and blanks\\
entab & - & Replace blanks with tabs and blanks\\
lcase & - & Convert a file to lower case\\
precess & - & Precess a list of astronomical coordinates\\
translit & - & Replace or delete specified characters in a file\\
ucase & - & Convert a file to upper case\\
urand & - & Uniform random number generator
\end{tabular}
\end{itemize}
\clearpage
\subsection{IRAF Editor Functions}
\begin{tabular}{llll}
Command & Emacs & EDT$^{\dag}$ & Vi$^{\ddag}$ \\
\\
move-up & \key{$\uparrow$} or \key{CTRL/P} & \key{$\uparrow$}
& \key{j} or \key{CTRL/P} \\
move-down & \key{$\downarrow$} or \key{CTRL/N} & \key{$\downarrow$}
& \key{k} or \key{CTRL/N} \\
move-right & \key{$\rightarrow$} or \key{CTRL/F} & \key{$\rightarrow$}
& \key{l} or \key{$\rightarrow$} \\
move-left & \key{$\leftarrow$} or \key{CTRL/B} & \key{$\leftarrow$}
& \key{h} or \key{$\leftarrow$} \\
\\
ins-chr/word & {\it text} & {\it text} & i/a-{\it text}\ \key{ESC} \\
del-left & \key{CTRL/H} or \key{DEL} \hspace{1cm} & \key{DEL} & \key{DEL} \\
del-char & \key{CTRL/D} & \key{,} & \key{x} \\
del-word & \key{ESC}\ \key{d} & \key{-} & \key{d}\ \key{w} \\
del-line & \key{CTRL/K} & \key{PF4} & \key{d} \key{d} \\
undel-char & \key{ESC}\ \key{CTRL/D} & \key{GOLD}\ \key{,} & \key{u} \\
undel-word & \key{ESC}\ \key{CTRL/W} & \key{GOLD}\ \key{-} & \key{u} \\
undel-line & \key{ESC}\ \key{CTRL/K} & \key{GOLD}\ \key{PF4} & \key{u} \\
\\
set-fwd & & \key{4} & \\
set-rev & & \key{5} & \\
next-word & \key{ESC}\ \key{f} & \key{1} & \key{w} \\
prev-word & \key{ESC}\ \key{b} & \key{5}\ \key{1} & \key{b} \\
move-eol & \key{CTRL/E} & \key{2} & \key{\$} \\
move-bol & \key{CTRL/A} & \key{BS} or \key{CTRL/H} \hspace{1cm}
& \key{.} \\
next-page & \key{CTRL/V} & \key{7} & \key{CTRL/D} or \key{CTRL/F} \\
prev-page & \key{ESC}\ \key{V} & \key{5}\ \key{7}
& \key{CTRL/U} or \key{CTRL/B} \\
move-start & \key{ESC}\ \key{$<$} & \key{GOLD}\ \key{5} & \key{1}\ \key{G} \\
move-end & \key{ESC}\ \key{$>$} & \key{GOLD}\ \key{4} & \key{G} \\
\\
get-help & \key{ESC}\ \key{?} & \key{PF2} & \key{PF2} or \key{ESC}\ \key{?} \\
repaint & \key{CTRL/L} & \key{CTRL/R} & \key{CTRL/L}\\
exit-update & \key{CTRL/Z} & \key{CTRL/Z}
& \key{:}\ \key{w}\ \key{q} \\
exit-no update \hspace{1cm} & \key{CTRL/C} & \key{CTRL/C}
& \key{:}\ \key{q}\ \key{!} \\
\end{tabular}
\hrule width5cm \vskip .15cm \noindent
\dag{} --- EDT employs the notion of ``direction'' (forward and backward
cursor motion). Several command sequences are preceded by \key{5} to indicate
explicitly that they only function after setting ``backward'' mode. All EDT
keystrokes, with the exception of \key{CTRL} keys, use the keypad.
\medskip \noindent
\ddag{} --- Vi has \emphasize{insert/replace/change modes},
which are entered by command and terminated by the \key{ESC} key.
Vi-type keystrokes for \usertype{eparam} and \usertype{ehist} are not
yet implemented.
\twocolumn \columnsep 1cm
\section{Glossary}
\medskip \noindent \irafname{AAS} --- American Astronomical Society.
\medskip \noindent \irafname{band} --- A two dimensional array. The Nth band
of a three dimensional array or \irafname{image} is denoted by the subscript
[$*$,$*$,N], where $*$ refers to all the pixels in that dimension.
\medskip \noindent \irafname{binary file} --- An array or sequence of
data words. Data is transferred between a binary file and a buffer in the
calling program by a simple copy operation, without any form of conversion.
\medskip \noindent \irafname{binary operator} --- An operator which combines
two operands to produce a single result
(e.g., the addition operator in $x + y$).
\medskip \noindent \irafname{brace} --- The left and right braces are
the characters `\{' and `\}'. Braces are used in the CL and in the
SPP language to group statements to form a compound statement.
\medskip \noindent \irafname{bracket} --- The left and right brackets
are the characters `[' and `]'. Brackets are used in the CL and in the
SPP language to delimit array subscripts.
\medskip \noindent \irafname{byte} --- The smallest unit of storage on
the host machine. The IRAF system assumes that there are an integral
number of bytes in a \irafname{char} and in an address increment
(and therefore that the byte is not larger than either).
On most modern computers, a byte is 8 bits, and a \irafname{char} is 16 bits
(I$*$2). If the address increment is one byte, the machine
is said to be \emphasize{byte addressable}. Other machines are \emphasize{word
addressable}, where one word of memory contains two or more bytes.
In the SPP language, SZB$_{CHAR}$ gives the number of bytes per char,
and SZB$_{ADDR}$ gives the number of bytes per address increment.
\medskip \noindent \irafname {C} --- A powerful modern language for
both systems and general programming.
C provides data structuring, recursion, automatic storage, a fairly
standard set of control constructs, a rich set of operators,
and considerable conciseness of expression.
\medskip \noindent \irafname{char} --- The smallest signed integer that can be
directly addressed by programs written in the SPP language. The char
is also the unit of storage in IRAF programs; the sizes of objects are
given in units of chars, and binary files and memory are addressed in
units of chars. Since the SPP language interfaces to the machine via the
local Fortran compiler, the Fortran compiler determines the size of a char.
On most systems, the IRAF data type \emphasize{char} is equivalent to the
(nonstandard) Fortran datatype I$*$2.
\medskip \noindent \irafname{CL} --- The IRAF Command Language. The CL is an
interpreted language designed to execute external \irafname{tasks}, and
to manage their \irafname{parameters}.
The CL organizes tasks into a hierarchical structure of independent
\irafname{packages}. Tasks may be either \irafname{script tasks}, written in
the CL, or compiled \irafname{programs}, written in the SPP language, and
linked together to form \irafname{processes}. A single process may contain
an arbitrary number of tasks.
The CL provides \irafname{redirection} of all I/O streams, including graphics
output, and cursor readback. Other facilities include command logging, an
on-line help facility, a ``programmable desk
calculator'' capability, and a \irafname{learn mode}.
New packages and tasks are easily added by the user,
and the CL environment is maintained in the user's own directories,
providing continuity from session to session.
\medskip \noindent \irafname{column} --- a one-dimensional array. The Nth
column vector of a two dimensional array or image is denoted
by the subscript [N,$*$],
where $*$ refers to all the pixels in that dimension.
The Nth column of the Mth band of a three dimensional array or image
is denoted by [N,$*$,M].
\medskip \noindent \irafname{coupling} --- A measure of the strength of
interdependence among modules.
The independence of modules is maximized when coupling is minimized.
\medskip \noindent \irafname{CTIO} --- Cerro Tollolo Image Observatory,
one of the NOAO facilities located in Chile.
\medskip \noindent \irafname{data structure} --- An aggregate of two or more
data elements, where the elements are not necessarily of the same type.
Examples include arrays, files, rec\-ords, linked lists,
trees, graphs, and so on.
\medskip \noindent \irafname{data file} --- a data storage file. Data
files are used to store program generated \irafname{records} or descriptors,
that contain the results
of the analysis performed by a program. Datafile records may be the
final output of a program, or may be used as input to a program. Data
file may contain ASCII or binary data, and may have implicit or explicit
data structures.
\medskip \noindent \irafname{environment variables} --- Parameters that
affect the operation of \emphasize{all} IRAF programs.
Environment variables define logical names for directories, associate
physical devices with logical device names, and provide control
over the low level functioning of the IRAF file I/O system.
\medskip \noindent \irafname{ECF} --- European Coordination Facility. The
center that is to coordinate use of Space Telescope data and programs for
the European scientific community.
\medskip \noindent \irafname{ESO} --- European Southern Observatory,
headquartered at Garching, FDR.
\medskip \noindent \irafname{field} --- An element of a \irafname{data
structure} or \irafname{record}. Each field has
a name, a datatype, and a value.
\medskip \noindent \irafname{FITS} --- Flexible Image Transport System. FITS is
a standard tape format used to transport images (pictures) between computers
and institutions. Developed in the late 1970s by Donald Wells (KPNO),
Eric Greisen (NRAO), and Ron Harten (Westerbork),
the FITS standard is now widely used for the
interchange of image data between astronomical centers, and is officially
sanctioned by both the AAS and the IAU.
\medskip \noindent \irafname{Fortran} --- As the most widely used language
for scientific computing for the past
twenty years, Fortran needs little introduction. Fortran is used in the
IRAF system as a sort of ``super assembler'' language. Programs and procedures
written in the IRAF \irafname{SPP} language are mechanically translated
into a highly
portable subset of Fortran, and the Fortran modules are in turn translated
into object modules by the host Fortran compiler. Existing numerical
and other modules, already coded in the Fortran language, are easily linked
with modules written in the SPP language to produce executable programs.
The IRAF system and applications software does not use any Fortran I/O;
all I/O facilities are provided by the IRAF \irafname{program interface} and
\irafname{virtual operating system}.
\medskip \noindent \irafname{function} --- A procedure which returns a value.
Functions must be declared before they can be used, and functions must only be
used in expressions. It is illegal to \emphasize{call} a function.
\medskip \noindent \irafname{HSI} --- The IRAF Host System Interface,
i.e., the interface between the portable IRAF software and the host system.
The HSI include the \irafname{kernel}, the \irafname{bootstrap utilities},
and any host dependent graphics device interfaces.
\medskip \noindent \irafname{hidden parameters} --- Parameters that
are not displayed by the CL.
The CL does not query for hidden parameters, but automatically
uses the default values. Hidden parameters may be set on the command line,
but the value from the command line will not be \irafname{learned}.
\medskip \noindent \irafname{IAU} --- The International Astronomical Union.
\medskip \noindent \irafname{IKI} --- The Image Kernel Interface. The IKI
gives IRAF the capability of dealing with multiple physical image storage
formats. The high level image i/o software calls the IKI, which in turn
calls one of the format specific image kernels, e.g., the OIF kernel or
the STF kernel.
\medskip \noindent \irafname{identifier} --- A sequence of characters used to
name a procedure, variable, etc. in a compiled language. In the CL and
SPP languages, an identifier is an upper or lower case letter, followed
by any number of upper or lower case letters, digits, or underscore characters.
\medskip \noindent \irafname{image} --- An array of arbitrary dimension
and datatype, used for bulk data storage.
An image is an array of \irafname{pixels}.
\medskip \noindent \irafname{imagefile} --- The form in which images are
stored in the IRAF system. IRAF currently supports images of up to seven
dimensions, in any of eight different data types.
Only \emphasize{line storage} mode is currently available, but support for
VMS mapped image sections is planned.
The imagefile structure is actually implemen\-ted as two separate files,
an \irafname{image head\-er file} and a \irafname{pixel storage file}.
\medskip \noindent \irafname{image header file} --- a file describing the
contents of an image. It is a small file that is normally placed in the
user's own directory system.
\medskip \noindent \irafname{interface} --- The visible portion of a
system, program or collection of programs. The only portion of such a
entity that other entities need to have knowledge of or access to.
The connection between hardware or software entities.
\medskip \noindent \irafname{IRAF} --- The Image Reduction and Analysis
Facility.
IRAF comprises a \irafname{virtual operating system}, a command language
(CL), a general purpose programming language (SPP, which
was developed along with IRAF), a large I/O library, and numerous support
utilities and scientific applications programs. The system is designed to be
transportable to any modern superminicomputer. The
system provides extensive facilities for general image processing,
astronomical data reduction and analysis, scientific programming,
and general software development.
\medskip \noindent \irafname{IRAF Guru} --- Any individual whose knowledge
of IRAF is greater than yours. Gurus' wisdom embraces all of the essential
mysteries of IRAF, and usually includes the locations of good Chinese
restaurants.
\medskip \noindent \irafname{kernel} --- A host dependent library of SPP
(or Fortran) callable subroutines implementing the primitive system services
required by the portable IRAF virtual operating system (VOS). Most of the
machine dependence of IRAF is concentrated into the kernel.
\medskip \noindent \irafname{learn mode} --- A facility designed
to simplify the use of the CL. By default, the CL ``learns'' the value of all
function \irafname{parameters} that are prompted for or explicitly set.
\medskip \noindent \irafname{line} --- A one-dimensional array. The Nth line
of a two dimensional array or image is denoted
by the subscript [$*$,N],
where $*$ refers to all the pixels in that dimension.
The Nth line of the Mth band of a three dimensional array or image
is denoted by [$*$,N,M].
\medskip \noindent \irafname{list structured parameter} --- A text file, each
line of which is a record that contains one or more fields, separated
by blanks or commas, that can be interpre\-ted by the CL.
Not all fields need be present, omitted fields are indicated by insertion
of an extra comma (fields can only be omitted
from right to left).
\medskip \noindent \irafname{Lroff} --- The text formatter that is part of
the portable IRAF system and used to process \irafname{help} file text.
Lroff is patterned after the UNIX \irafname{Troff} text formatter.
\medskip \noindent \irafname{macro} --- (1) A \irafname{script task}.
(2) An inline function with zero or more arguments that is
expanded by text substitution during the preprocessing phase
of compilation.
\medskip \noindent \irafname{metacharacter} --- Characters that have special
meaning to the CL. For example, the asterisk `$*$' is used as a ``wild card''
place-holder; any alphanumeric character is considered a match.
\medskip \noindent \irafname{MIDAS} --- Munich Image Data Analysis System.
An analysis package under development by the ESO.
\medskip \noindent \irafname{NOAO} --- National Optical Astronomy
Observatories.
\medskip \noindent \irafname{NRAO} --- National Radio Astronomy Observatory.
\medskip \noindent \irafname{operand} --- A data object that is
operated upon by an operator, \irafname{procedure}, or \irafname{task}.
Operands may be used for either input or output, or both.
\medskip \noindent \irafname{OIF} --- The old IRAF image format. Refers to the
physical format in which images are stored on disk, as well as to the
\irafname{IKI} kernel used to access images stored externally in the OIF format.
\medskip \noindent \irafname{OS} --- Operating System.
\medskip \noindent \irafname{package} --- (1) A collection of modules that
are logically related (e.g., the set of \irafname{system} utilities).
(2) A set of modules that operates on
a specific \emphasize{abstract datatype}. The modules in a package may be
either \irafname{procedures} or \irafname{tasks}.
Examples of abstract datatypes include the CL, the file,
the \irafname{imagefile}, and so on.
\medskip \noindent \irafname{parameter} --- An externally supplied
argument to a module which directly controls the functioning of the module.
\medskip \noindent \irafname{pathname} --- An absolute OS-dependent filename
specification.
\medskip \noindent \irafname{pipe} --- An abstraction that connects the output
of one \irafname{task} to the input of another. The implementation of pipes
is OS-dependent.
\medskip \noindent \irafname{pixel} --- Picture element. The fundamental unit
of storage in an \irafname{image}.
\medskip \noindent \irafname{pixel storage file} --- a file that contains image
pixel data. Typically, it is a bulky file and for this reason it is usually
placed in a file system designated for such files.
\medskip \noindent \irafname{portable} --- A program is said to be portable
from computer A to computer B if it can be moved from A to B without change
to the source code.
A program is said to be \emphasize{transportable} from computer A to computer B
if the effort required to move the program from A to B is much less than the
effort required to write an equivalent program on machine B from scratch.
\medskip \noindent \irafname{positional parameters} --- Parameters
that are required for the execution of a given \irafname{function},
and will be queried for by the CL if not given on the command line. Positional
\emphasize{arguments} are the first arguments on the command line (following
the command), and they are associated with parameters by their position
on the command line. The first positional parameter will be set by the first
positional argument on the command line, the second positional parameter by
the second positional argument, and so on.
\medskip \noindent \irafname{preprocessor} --- A program which transforms the
text of a source file prior to compilation. A preprocessor, unlike a compiler,
does not fully define a language. A preprocessor transforms only those
constructs which it understands; all other text is passed on to the compiler
without change. The SPP language is implemented as a pre-processor.
\medskip \noindent \irafname{procedure} --- A separately compiled program unit.
The procedure is the primary construct provided by programming languages for
the \emphasize{abstraction of function}.
The external characteristics of a procedure are its name, argument list,
and optional return value.
\medskip \noindent \irafname{process} --- An executable partition of
memory in the host computer.
The host OS initiates a process by copying or mapping an executable file
into main memory. In a multitasking and multiuser system, a number of processes
will generally be resident simultaneously in main memory,
and the processor will execute each in turn.
\medskip \noindent \irafname{program} --- A compiled procedure called by the
CL. The procedure must be referenced in a \irafname{task} statement before it
can be accessed by the CL. An arbitrary number of programs may be
linked to form a single \irafname{process}.
\medskip \noindent \irafname{program interface} --- The interface between an
applications program and everything else. In IRAF, the program interface
defines access to all I/O devices, system services, files, and several
other non-computational facilities that pro\-grams require.
\medskip \noindent \irafname{record} --- A \irafname{data structure} consisting
of an arbitrary set of fields, used to pass information between program modules
or to permanently record the results of an analysis program in a
\irafname{data file}.
\medskip \noindent \irafname{redirection} --- The allocation of an input or
output stream to something other than the standard device. For example,
\irafname{tasks} can be made to write output to files instead of terminals
and the output of one task may be redirected to the input of another.
\medskip \noindent \irafname{script task} --- An interpreted program written
in the CL. A script task, like a compiled program, may have formal parameters
and local variables. A script task may call another task, including another
script task, but may not call itself.
To the caller, script tasks and compiled programs are equivalent.
\medskip \noindent \irafname{SDAS} --- Science Data Analysis System. A set
of applications routines that are under development at STScI.
\medskip \noindent \irafname{SPP} --- The IRAF Subset Preprocessor Language.
A general purpose language patterned after Ratfor and C, the SPP provides
advanced capabilities, modern control constructs, enhanced portability,
and support for the IRAF runtime library (CL interface, etc.).
\medskip \noindent \irafname{STF} --- The STScI SDAS group data image format.
Refers to the physical format in which images are stored on disk, as well as
to the \irafname{IKI} kernel used to access images stored externally in the
STF format.
\medskip \noindent \irafname{STScI} --- Space Telescope Science Institute.
\medskip \noindent \irafname{system interface} --- The interface between
the portable IRAF software and the host operating
system. The system interface is a \irafname{virtual operating system}.
The system interface routines, described in \reference{A Reference Manual
for the IRAF System Interface}
are in principle the only parts of a system that need to be changed
when porting the system to a new computer.
\medskip \noindent \irafname{task} --- A CL callable program unit.
CL tasks may be script tasks, external programs,
or compiled procedures which are built in to the CL.
\medskip \noindent \irafname{task statement} --- (1) The CL statement that
enters the name of a task in the IRAF task dictionary,
defines the type of task, and in the case of a compiled task, the name of
the process in which it resides.
(2) The statement in the SPP language that defines a list of programs
to be linked together to form a single process.
\medskip \noindent \irafname{template} --- A string consisting of one or more
names, which may or may not contain patterns
(with \irafname{metacharacters}).
\medskip \noindent \irafname{text file} --- A file which contains only
text (ASCII character data), and which is maintained
in the form expected by the text processing tools of the host OS.
\medskip \noindent \irafname{Troff} --- The UNIX text formatter.
\medskip \noindent \irafname{unary operator} --- An operator which operates on
a single operand, e.g., the minus sign in the expression ``$-x$''.
\medskip \noindent \irafname{UNIX} --- An operating system developed at Bell
Labs in the early 1970s by Ken Thompson and Dennis Ritchie. Originally
developed for the PDP11, UNIX is now available on a wide range of machines,
ranging from micros to superminis, mainframes, and supercomputers.\\
UNIX is the software development system for the IRAF project at NOAO.
\medskip \noindent \irafname{virtual file} --- A file that uses a machine
independent filename within IRAF. The virtual filename is mapped to its
host OS counterpart by the CL.
\medskip \noindent \irafname{virtual memory} --- A form of addressing that
enables a process to address locations that are not in physical memory.
The amount of physical memory available to a process is known as the
\emphasize{working set} of a process; the virtual address space is organized
into a series of fixed size \emphasize{pages}. Pages which are not
\emphasize{memory resident}, i.e., not in the working set, reside on some form
of backing store, usually a disk file. When a page is referenced which is not
in the working set, a \emphasize{page fault} occurs, causing the page to be
read into the working set.
\medskip \noindent \irafname{virtual operating system} --- A set of system
calls that define primitive functions comparable
to those provided by an actual operating system.
IRAF provides routines (the so-called
\irafname{program interface}) for file access, process initiation and control,
exception handling, logical names, etc.
\medskip \noindent \irafname{VMS} --- The native operating system for the
Digital VAX series of supermini computers.
\medskip \noindent \irafname{VOS} --- The IRAF Virtual Operating System.
The VOS implements all of the basic functionality provided by IRAF, and defines
the environment in which applications programs are written. For example,
the VOS provides facilities for file access, image access, access to graphics
and image display devices, access to the command language to fetch parameters
etc., process control and exception handling facilities, and so on. The VOS
is written in portable SPP using the facilities provided by the IRAF
\irafname{kernel}.
\medskip \noindent \irafname{Z-routines} --- Machine dependent routines used
to interface to the host operating system. The IRAF Z-routines are maintained
in the package \taskname{OS}.
\onecolumn
\end{document}
distrib
>
Mageia
>
6
>
armv5tl
>
media
>
core-release
>
by-pkgid
>
30819c093f498f9dfa6444d2407d0521
>
files
>
5320
