path: root/sys/imfort/doc/imfort.ms

.RP
.TL
A User's Guide to Fortran Programming in IRAF
.br
The IMFORT Interface
.AU
Doug Tody
.AI
.K2 "" "" "*"
September 1986

.AB
The IMFORT interface is a Fortran programming environment suitable for general
Fortran programming, with special emphasis on batch image processing.
IMFORT is intended for use primarily by the scientist/user who occasionally
needs to write a program for their own personal use, but who does not program
often enough to make it worthwhile learning a larger, more complex but fully
featured programming environment.  IMFORT is therefore a small interface which
is easy to learn and use, and which relies heavily upon host system (non-IRAF)
facilities which the user is assumed to already be familiar with.
Facilities are provided for accessing command line arguments, reading and
writing IRAF images, and returning output to the CL.  Provisions are made
for editing, compiling, linking, and debugging programs without need to leave
the IRAF environment, making use of familiar host system editing and debugging
tools wherever possible.
.AE

.NH
Introduction
.PP
The IMFORT interface is a library of Fortran callable subroutines which can
be called from a host system Fortran program to perform such operations as
fetching the arguments given on the command line when the task was invoked,
or accessing the header or pixel information in an IRAF image (bulk data frame).
Since the result is a host program rather than an IRAF program, only limited
access to the facilities provided by the runtime IRAF system is possible,
but on the other hand one has full access to the facilities provided by the
host system.  Programs which use IMFORT may be run as ordinary host system
programs outside of IRAF, or may be interfaced to the IRAF command language
(CL) as CL callable tasks.  Within the IRAF environment these user written,
non-IRAF tasks behave much like ordinary IRAF tasks, allowing background
execution, use of i/o redirection and pipes, evaluation of expressions on
the command line, programmed execution in scripts, and so on.

.NH 2
Who Should Use IMFORT
.PP
The most significant feature of the IMFORT interface is that it is designed
for use by \fIhost\fR Fortran programs.  The scientist/user will often already
be using such programs when IRAF becomes available.  IMFORT allows these
pre-existing programs to be modified to work within the IRAF environment
with a minimum of effort and with minimum changes to the existing program.
The only alternative is to rework these programs as \fIIRAF\fR programs,
but few existing Fortran programs could (or should) survive such a transition
without being completely rewritten.  If the program in question is useful
enough such a rewrite might be warranted, but in most cases this will not
be practical, hence something like the IMFORT interface is clearly needed
to keep these old programs alive until they are no longer needed.
.PP
The second goal of the IMFORT interface is to provide a way for the user to
add their own programs to IRAF without having to invest a lot of time learning
the full blown IRAF programming environment.  IMFORT makes it possible for
the user to begin writing useful programs within hours of their first exposure
to the system.  It is possible that the IMFORT interface will provide all the
capability that some users will ever need, especially when supplemented by other
(non-IRAF) Fortran callable libraries available on the local host machine.
Programs developed in this way are bound to have portability and other
problems, but it should be up to the developer and user of the software to
decide whether these problems are worth worrying about.  IMFORT is simply
a \fItool\fR, to be used as one sees fit; there is no attempt to dictate to
the user how they should write their programs.
.PP
The alternative to IMFORT, if applications programming within IRAF is the goal,
is the IRAF SPP/VOS programming environment.  The SPP/VOS programming
environment is a fully featured scientific programming environment which
carefully addresses all the software engineering issues avoided by IMFORT.
The VOS is a large and complex environment and therefore takes longer to learn
than IMFORT, but it provides all the facilities needed by large applications
hence is \fIeasier\fR to use than simpler interfaces like IMFORT, if one is
faced with the already difficult task of coding a large program or package.
Furthermore, the SPP/VOS environment fully addresses the problems of
portability and device independence, critical issues for applications which
must be supported and used simultaneously on a range of machines over a
period of years, during which time the software is likely to be continually
evolving.  An overview of the SPP/VOS programming environment is given in
\fIThe IRAF Data Reduction and Analysis System\fR, February 1986, by the author.
.PP
In summary, IMFORT is intended for use to interface old Fortran programs to
IRAF with a minimum of effort, and as an entry level programming environment
which new users can learn to use in a few hours.  Experienced users,
professional programmers, and developers of large applications will find that
they can accomplish more with less effort once they have learned to use the
more fully featured SPP/VOS programming environment.

.bp
.NH
Getting Started
.PP
Although programs which use IMFORT can and often will be invoked from the
host system command interpreter, it is likely that such programs will also
be used interactively in combination with the tasks provided by the standard
IRAF system.  For example, the IRAF graphics and image display facilities
are likely to be used to examine the results of an image operation performed
by a user written Fortran/IMFORT program.  Indeed, the standard IRAF tasks
are likely to be used for testing new IMFORT programs as well as reducing data
with old ones, so we shall assume that software development will take place
from within the IRAF environment.  Since IRAF provides full access to the
facilities of the host system at all times, there is little reason not to
work from within the IRAF environment.
.PP
As a first step, let's see what is required to enter, compile, link, and
execute a small Fortran program which does nothing more than print the
message \fLhello, world!\fR on the terminal.  We shall assume that the
reader has read the \fICL User's Guide\fR and is already familiar with
basic CL command entry, the OS escape facility, the editor interface and so on.
The first step is to call up the editor to enter the program into a file:
.DS
\fLcl> edit hello.f\fR
.DE
Note that the filename extension is ".f", which is what IRAF uses for
Fortran files.  The extension will be mapped into the local host system
equivalent when IRAF communicates with the host system, but when working
in the IRAF environment the IRAF name should be used.
.LP
Once in the editor, enter the following program text:
.DS
\fLprogram hello
write (*,*) 'hello, world!'
stop
end\fR
.DE
The next step is to compile and link the \fLhello\fR program.  This is done
by the command \fIfc\fR (\fIf\fRortran-\fIc\fRompile), which produces an
object file \fLhello.o\fR and an executable program file \fLhello.e\fR.
Note that the \fIfc\fR task is defined in the default \fIuser\fR package in
your \fLLOGIN.CL\fR file, hence a \fImkiraf\fR may be required to regenerate
the \fLLOGIN.CL\fR file if the file is old or has been modified.
.DS
\fLcl> fc hello.f\fR
.DE
Since the \fLhello\fR program is a host Fortran program, it can be executed
immediately with an OS escape, e.g., \fL!hello.e\fR on UNIX, or
\fL!run hello\fR on VMS.  A better approach if the task has command line
arguments is to use the IRAF \fIforeign task\fR facility to define the
program as a new IRAF task, as we shall see in the next section.

.NH 2
Example 1:  Plotting a function
.PP
As a slightly more complicated example, let's construct a program to compute
and plot a function using command line arguments to input the function
parameters, with output consisting of a simple ASCII table sampling the
computed function.  Our example computes the Planck function, which gives the
emissivity of a blackbody as a function of wavelength and temperature.
The sample program is shown in Figure 1.  Source code for this and all other
examples in this paper may be found in the IRAF directory \fLimfort$tasks\fR.

.DS
\fL
.ps 8
.vs 9p
c PLANCK -- Compute the Planck blackbody radiation distribution for a
c given temperature and wavelength region.
c
c       usage:  planck temperature lambda1 lambda2
c
c The temperature is specified in degrees Kelvin and the wavelength
c region in microns (1u=10000A).  100 [x,y] data points defining the
c curve are output.
c ----------------------------------------------------------------------

        program planck

        character*80    errmsg
        integer         nargs, ier, i
        real            w1, w2, dw, cm, t
        real            xv(100), yv(100)

c --- Get the temperature in degrees kelvin.
        call clargr (1, t, ier)
        if (ier .ne. 0) then
            write (*, '('' temperature (degrees kelvin): '',$)')
            read (*,*) t
        endif

c --- Get the wavelength region to be computed.
        call clnarg (nargs)
        if (nargs .ge. 3) then
            call clargr (2, w1, ier)
            if (ier .ne. 0) goto 91
            call clargr (3, w2, ier)
            if (ier .ne. 0) goto 91
        else
            write (*, '('' start wavelength (microns): '',$)')
            read (*,*) w1
            write (*, '('' end wavelength (microns): '',$)')
            read (*,*) w2
        endif

c --- Compute the blackbody curve.
        dw = (w2 - w1) / 99.0
        do 10 i = 1, 100
            xv(i) = ((i-1) * dw) + w1
            cm = xv(i) * 1.0E-4
            yv(i) = (3.74185E-5 * (cm ** -5)) /
     *          (2.71828 ** (1.43883 / (cm * t)) - 1.0)
 10     continue

c --- Print the curve as a table.
        do 20 i = 1, 100
            write (*, '(f7.4, g12.4)') xv(i), yv(i)
 20     continue

        stop

c --- Error exit. 
 91     call imemsg (ier, errmsg)
        write (*, '('' Error: '', a80)') errmsg
        stop
        end\fR
.DE
.vs
.ps
.sp
.ce
Figure 1.  Sample program to compute the Planck function\(dd
.FS
\(ddThe trailing \fL$\fR carriage control code used in the format strings in
the \fLWRITE\fR statements in this and the other sample Fortran programs
is nonstandard Fortran and may not be available on all host machines.
Its function is to defeat the carriage-return linefeed so that the user's
response may be entered on the same line as the prompt.
.FE

.PP
This example serves to demonstrate the use of the IMFORT \fIclarg\fR procedures
to fetch the command line arguments, and the use of i/o redirection to capture
the output to generate the plot.  The command line to an IMFORT program consists
of a sequence of arguments delimited by spaces or tabs.  The subroutine
\fIclnarg\fR returns the number of arguments present on the command line when
the task was called.  The \fIclargr\fR, \fIclargi\fR, etc. procedures fetch
and decode the values of the individual arguments.  Virtually all IMFORT
procedures include an integer output variable \fIier\fR in their argument list;
a zero status indicates success, anything else indicates failure and the actual
error code identifies the cause of the problem.  The \fIimemsg\fR procedure
may be called to convert IMFORT error codes into error message strings, as in
the example.
.PP
Once the program has been entered and compiled and linked with \fIfc\fR,
we must declare the program as a foreign task to the CL.  If this is not
done the program can still be run via an OS escape, but none of the advanced
CL features will be available, e.g., background execution, command line
expression evaluation, i/o redirection, and so on.  The technique used to
declare a foreign task is machine dependent since it depends upon the syntax
of the host command interpreter.  For example, to declare the new CL foreign
task \fIplanck\fR on a UNIX system, we enter the following command:
.DS
\fLcl> task $planck = $planck.e\fR
.DE
The same thing can be achieved on a VMS system with the following
declaration (it can be simplified by moving the VMS foreign task declaration
to your \fLLOGIN.COM\fR file):
.DS
\fLcl> task $planck = "$planck:==\\\\$\fIdisk\fP:[\fIdir\fP...]planck.exe!planck"\fR
.DE
The \fL$\fR characters are required to tell the CL that the new task does
not have a parameter file, and is a foreign task rather than a regular
IRAF task.  The \fL!\fR in the VMS example is used to delimit multiple DCL
commands; the command shown defines the DCL foreign task \fIplanck\fR and
then executes it.  The use of the \fItask\fR statement to declare foreign
tasks is discussed in detail in \(sc3.3.
.PP
We have written the program in such a way that the arguments will be queried
for if not given on the command line, so if we enter only the name of the
command, an interaction such as the following will occur:
.DS
\fLcl> planck
temperature (degrees kelvin): 3000
start wavelength (microns): .1
end wavelength (microns): 4\fR
.DE
Note that if the output of the \fIplanck\fR task is redirected this input
mechanism will \fInot\fR work, since the queries will be redirected along
with the output.  Hence if we use a pipe to capture the output, as in the
following example, the arguments must be given on the command line.
.DS
\fLcl> planck 3000 0.1 4.0 | graph
.DE
This command will compute and plot the emissivity for a 3000 degree kelvin
blackbody from 0.1 to 4.0 microns (1000 to 40000 angstroms).
.PP
An interesting alternative way to implement the above program would be to
output the function curve as a line in an image, rather than as a table of
numbers.  For example, a two dimensional image could be generated wherein
each line corresponds to a different temperature.  \fIGraph\fR or \fIimplot\fR
could then be used to plot curves or overplot families of curves; this would
be more efficient than the technique employed in our sample program.
Image access via IMFORT is illustrated in our next example.

.NH 2
Example 2:  Compute the range of pixel values in an image
.PP
The program shown in Figure 2 opens the named image, examines each line in
the image to determine the minimum and maximum pixel values, keeping a running
tally until the entire image has been examined (there is no provision for
detecting and ignoring bad pixels in the image).  The newly computed minimum
and maximum pixel values are then updated in the image header as well as
printed on the standard output.
.DS
\fL
.ps 8
.vs 9p
c MINMAX -- Compute the minimum and maximum pixel values in an image.
c The new values are printed as well as updated in the image header.
c
c       usage:  minmax image
c ----------------------------------------------------------------------

        program minmax

        character*80    image, errmsg
        real            pix(4096), dmin, dmax, vmin, vmax
        integer         im, axlen(7), naxis, dtype, ier, j

c --- Get image name.
        call clargc (1, image, ier)
        if (ier .ne. 0) then
            write (*, '('' enter image name: '',$)')
            read (*,*) image
        endif

c --- Open the image for readwrite access (we need to update the header).
        call imopen (image, 3, im, ier)
        if (ier .ne. 0) goto 91
        call imgsiz (im, axlen, naxis, dtype, ier)
        if (ier .ne. 0) goto 91

c --- Read through the image and compute the limiting pixel values.
        do 10 j = 1, axlen(2)
            call imgl2r (im, pix, j, ier)
            if (ier .ne. 0) goto 91
            call alimr (pix, axlen(1), vmin, vmax)
            if (j .eq. 1) then
                dmin = vmin
                dmax = vmax
            else
                dmin = min (dmin, vmin)
                dmax = max (dmax, vmax)
            endif
 10     continue

c --- Update the image header.
        call impkwr (im, 'datamin', dmin, ier)
        if (ier .ne. 0) goto 91
        call impkwr (im, 'datamax', dmax, ier)
        if (ier .ne. 0) goto 91

c --- Clean up.
        call imclos (im, ier)
        if (ier .ne. 0) goto 91
        write (*, '(a20, 2 g12.5)') image, dmin, dmax
        stop

c --- Error exit.
 91     call imemsg (ier, errmsg)
        write (*, '('' Error: '', a80)') errmsg
        stop
        end\fR
.DE
.vs
.ps
.sp
.ce
Figure 2.  Compute the min and max pixel values in an image

.PP
The program as written can only deal with images of one or two dimensions,
of pixel type short (16 bit integer) or real (32 bit floating), with a line
length not to exceed 4096 pixels per line.  We could easily change the program
to deal with images of up to three dimensions, but the IMFORT interface does
not provide dynamic memory allocation facilities so there is always going
to be an upper limit on the line length if we use the simple get line i/o
procedure \fIimgl2r\fR, as shown.  The use of fixed size buffers simplifies
the program, however, and is not expected to be a serious problem in most
IMFORT applications.
.PP
The \fIalimr\fR subroutine in the previous example is from the IRAF VOPS
(vector operators) package.  The function of \fIalimr\fR is to compute
the limiting (min and max) pixel values in a vector of type real, the
function type being indicated by the \fIlim\fR, and the pixel datatype by
the \fIr\fR.  The VOPS package provides many other such vector operators,
and is discussed further in \(sc 4.4.

.NH 2
Example 3:  Copy an image
.PP
Our final example (Figure 3) shows how to create a new image as a copy of
some existing image.  This can be used as a template to create any binary
image operator, i.e., any program which computes some transformation upon
an existing image, writing a new image as output.
.PP
By now the functioning of this procedure should be self evident.
The only thing here which is at all subtle is the subroutine \fIimopnc\fR,
used to open (create) a new copy of an existing image.  The open new copy
operation creates a new image the same size and datatype as the old
image, and copies the image header of the old image to the new image.
Any user keywords in the header of the old image will be automatically
passed to the new image, without requiring that the calling program
have explicit knowledge of the contents of the image header.
.PP
Note that the program is written to work only on pixels of type real,
hence will be inefficient if used to copy images of type short-integer.
A more efficient approach for a general image copy operator would be
to add a conditional test on the variable \fLdtype\fR, executing a
different copy-loop for each datatype, to avoid having to convert from
integer to real and back again when copying a short-integer image.
The short-integer equivalents of \fIimgl3r\fR (get line, 3 dim image,
type real) and \fIimpl3r\fR (put line, 3 dim image, type real) are
called \fIimgl3s\fR and \fIimpl3s\fR.
.PP
The program as written will work for images of up to three dimensions,
even though it is written to deal with only the three dimensional case.
This works because the length of the "unused" axes in an image is
set to one when the image is created.  A program passed an image of
higher dimension than it is written for will also work, but will not
process all of the data.  IMFORT does not support image sections,
so only the first few lines of the image will be accessible to such
a program.

.PP
Additional useful examples of Fortran programs using IMFORT are given in
\fLimfort$tasks\fR.  These include utility programs to make test images,
print the contents of an image header, print the values of the pixels in
a subraster, and so on.  You may wish to copy the source for these to your
own workspace for use as is, or for use as templates to construct similar
programs.

.DS
\fL
.ps 8
.vs 9p
c IMCOPY -- Copy an image.  Works for images of up to three dimensions
c with a pixel type of short or real and up to 4096 pixels per line.
c
c       usage:  imcopy oldimage newimage
c ---------------------------------------------------------------------

        program imcopy

        real            pix(4096)
        character*80    oimage, nimage, errmsg
        integer         ncols, nlines, nbands, j, k, oim, nim
        integer         ier, axlen(7), naxis, dtype, nargs

c --- Get command line arguments.
        call clnarg (nargs)
        if (nargs .eq. 2) then
            call clargc (1, oimage, ier)
            if (ier .ne. 0) goto 91
            call clargc (2, nimage, ier)
            if (ier .ne. 0) goto 91
        else
            write (*, '('' input image: '',$)')
            read (*,*) oimage
            write (*, '('' output image: '',$)')
            read (*,*) nimage
        endif

c --- Open the input image and create a new-copy output image.
        call imopen (oimage, 1, oim, ier)
        if (ier .ne. 0) goto 91
        call imopnc (nimage, oim, nim, ier)
        if (ier .ne. 0) goto 91

c --- Determine the size and pixel type of the image being copied.
        call imgsiz (oim, axlen, naxis, dtype, ier)
        if (ier .ne. 0) goto 91

        ncols  = axlen(1)
        nlines = axlen(2)
        nbands = axlen(3)

c --- Copy the image.
	do 15 k = 1, nbands
	    do 10 j = 1, nlines
		call imgl3r (oim, pix, j, k, ier)
		if (ier .ne. 0) goto 91
		call impl3r (nim, pix, j, k, ier)
		if (ier .ne. 0) goto 91
 10         continue
 15     continue

c --- Clean up.
        call imclos (oim, ier)
        if (ier .ne. 0) goto 91
        call imclos (nim, ier)
        if (ier .ne. 0) goto 91

        stop

c --- Error actions.
 91     call imemsg (ier, errmsg)
        write (*, '('' Error: '', a80)') errmsg
        stop
        end\fR
.DE
.vs
.ps
.sp
.ce
Figure 3.  Image copy program

.bp
.NH
The IMFORT Programming Environment
.PP
IRAF provides a small programming environment for the development of host
Fortran programs using the IMFORT interface.  This environment consists
of the general CL tools, e.g., the editor, the \fIpage\fR and \fIlprint\fR
tasks, etc., plus a few special tools, namely, the \fIfc\fR compile/link
utility and the foreign task facility.  In this section we discuss these
special tools and facilities.  Information is also provided for linking
to the IMFORT libraries if program development is to take place at the host
system level.
.PP
The classic third generation program development cycle (ignoring such minor
details as designing the software) is edit \(em compile/link \(em debug.
The edit phase uses the CL \fIedit\fR task, an interface to the host system
editor of choice.  The compile/link phase is performed by the \fIfc\fR utility.
The debug phase is optional and is generally only necessary for large programs.
The host system debug tool is used; while IRAF does not provide a special
interface to the host debug tool, one can easily be constructed using the
foreign task facility if desired.
.PP
Programs which use the IMFORT interface are inevitably host system dependent
to some degree, since they are host programs.  In the interests of providing
the user with concrete examples, the discussion in this section must therefore
delve into the specifics of certain host operating systems.  We have chosen
to use UNIX and VMS in the examples, since most IRAF implementations run on
one or the other of these operating systems.  The ties between the IMFORT
programming environment and the host system are quite simple, however, so it
should not be difficult to see how to modify the examples for a different host.

.NH 2
The FC Compile/Link Utility
.PP
The \fIfc\fR utility provides a consistent, machine independent interface to
the host system compiler and linker which is convenient and easy to use.
In addition, \fIfc\fR provides a means for linking host programs with the
IRAF libraries without having to type a lot, and without having to build
host command scripts.  All of the IRAF libraries are accessible via \fIfc\fR,
not just IMFORT (\fLlib$libimfort.a\fR) and the IRAF system libraries used
by IMFORT, but all the other IRAF libraries as well, e.g., the math libraries.
.PP
The default action of \fIfc\fR is to compile and link the files listed on the
command line, i.e., source files in various languages, object modules, and
libraries.  Any source files are first turned into object modules, then the
objects are linked in the order given, searching any libraries in the order
in which they are encountered on the command line (the IMFORT libraries are
searched automatically, after any libraries listed on the command line).
By default, the root name of the new executable will be the same as that of
the first file listed on the command line; a different name may be assigned
with the \fI-o\fR switch if desired.
.LP
The syntax of the \fIfc\fR command is as follows:
.DS
\fLfc [\fIswitches\fP] \fIfile\fL [\fIfile ...\fL] [-o \fIexefile\fL]\fR
.DE
The most interesting switches are as follows:
.in 0.5i
.IP \fB-c\fR
Compile but do not link.
.IP \fB-l\fIlibrary\fR
.br
Link to the named IRAF library.  On a UNIX host this switch may also be
used to reference the UNIX libraries.  The \fI-llibrary\fR reference
should be given in the file list at the point at which you want the
library to be searched.  The \fI-l\fR causes \fIfc\fR to look in a set
of standard places for the named library; user libraries should be
referenced directly by the filename of the library.
.IP \fB-o\fR\ \fIexefile\fR
.br
Override the default name for the executable file produced by the linker.
.IP \fB-x\fR
Compile and link for debugging.
.in

.LP
Since the \fIfc\fR command line can contain many different types of objects,
a filename extension is required to identify the object type.  The IRAF
filename extensions \fImust\fR be used; these are listed in the table below.

.TS
box center;
cb s
ci | ci
c | l.
IRAF Filename Extensions
_
extn	usage
=
\.a	object library
\.c	C source file
\.e	executable
\.f	Fortran source file
\.o	object module
\.s	Assembler source file
\.x	SPP source file
.TE

.PP
The \fIfc\fR utility is easy to learn and use.  Here are a few examples
illustrating the most common usage of the utility.  To compile and link the
Fortran program \fLprog.f\fR, producing the executable program \fLprog.e\fR:
.DS
\fLcl> fc prog.f\fR
.DE
To compile the file \fLutil.f\fR to produce the object \fLutil.o\fR,
without linking anything:
.DS
\fLcl> fc -c util.f\fR
.DE
To link \fLprog.o\fR and \fLutil.o\fR, producing the executable program
\fLprog.e\fR:
.DS
\fLcl> fc prog.o util.o\fR
.DE
To do the same thing, producing an executable named \fLfoo.e\fR instead
of \fLprog.e\fR:
.DS
\fLcl> fc prog.o util.o -o foo.e\fR
.DE
To compile and link \fLprog.f\fR for debugging:
.DS
\fLcl> fc -x prog.f\fR
.DE
To link \fLprog.o\fR with the IRAF library \fLlib$libdeboor.a\fR (the DeBoor
spline package), producing the executable \fLprog.e\fR as output:
.DS
\fLcl> fc prog.o -ldeboor\fR
.DE
To do the same thing, spooling the output in the file \fLspool\fR and
running the whole thing in the background:
.DS
\fLcl> fc prog.o -ldeboor >& spool &\fR
.DE
To link instead with the library \fLlibfoo.a\fR, in the current directory
(note that in this case the library is a module and not a switch):
.DS
\fLcl> fc prog.o libfoo.a\fR
.DE
.LP
Just about any combination of switches and modules that makes sense will
work.  The order of libraries in the argument list is important, as they
will be searched in the order in which they are listed on the command line.
.PP
The \fIfc\fR utility is actually just a front-end to the standard IRAF
compiler \fIxc\fR, as we shall see in \(sc3.3.  See the manual page for
\fIxc\fR for additional information.

.NH 2
Host Level Linking to the IMFORT Libraries
.PP
In some cases it may be desirable to use host system facilities to compile
and link programs which use the IMFORT interface.  The procedure for doing
this is host dependent and is completely up to the user, who no doubt will
already have a preferred technique worked out.  All one needs to know in
this situation are the names of the libraries to be linked, and the order
in which they are to be linked.  The libraries are as follows, using the
IRAF filenames for the libraries.  All the libraries listed are referenced
internally by the IMFORT code hence are required.

.TS
center;
l l.
lib$libimfort.a	IMFORT itself
lib$libsys.a	Contains certain pure code modules used by IMFORT
lib$libvops.a	The VOPS vector operators library
hlib$libos.a	The IRAF kernel (i/o primitives)
.TE
.LP
The host pathnames of these libraries will probably be evident, given the
host pathname of the IRAF root directory (\fIlib\fR is a subdirectory of
the IRAF root directory).  If in doubt, the \fIosfn\fR intrinsic function may
be used while in the CL to print the host pathname of the desired library.
For example,
.DS
\fLcl> = osfn ("lib$libimfort.a")\fR
.DE
will cause the CL to print the host pathname of the main IMFORT library.

.NH 2
Calling Host Programs from the CL
.PP
Since Fortran programs which use IMFORT are host programs rather than IRAF
programs, the CL \fIforeign task\fR interface is used to connect the programs
to the CL as CL callable tasks.  The foreign task interface may also be used
to provide custom CL task interfaces to other host system utilities, e.g.,
the debugger or the librarian.
.PP
The function of the \fItask\fR statement in the CL is to make a new task
known to the CL.  The CL must know the name of the new task, the name of
the package to which it is to be added, whether or not the new task has a
parameter file, the type of task being defined, and the name of the file in
which the task resides.  At present new tasks are always added to the
"current" package.  The possible types of tasks are normal IRAF executable
tasks, CL script tasks, and foreign tasks.  Our interest here is only in the
forms of the task statement used to declare foreign tasks.  There are two
such forms at present.  The simplest is the following:
.DS
\fLtask $\fItaskname\fR [, \fL$\fItaskname\fR...]\fL = $foreign\fR
.DE
This form is used when the command to be sent to the host system to run
the task is identical to the name by which the task is known to the CL.
Note that any number of new tasks may be declared at one time with this
form of the task statement.  The \fL$\fR prefixing each \fItaskname\fR
tells the CL that the task does not have a parameter file.  The \fL$foreign\fR
tells the CL that the new tasks are foreign tasks and that the host command
is the same as \fItaskname\fR.  For example, most systems have a system
utility \fImail\fR which is used to read or send electronic mail.
To declare the \fImail\fR task as an IRAF foreign task, we could enter
the following declaration, and then just call the \fImail\fR task from
within the CL like any other IRAF task.
.DS
\fLtask $mail = $foreign\fR
.DE
The more general form of the foreign task statement is shown below.
The host command string must be quoted if it contains blanks or any other
special characters; \fL$\fR is a reserved character and must be escaped
to be included in the command sent to the host system.
.DS
\fLtask $\fItaskname\fL = $\fIhost_command_string\fR
.DE
In this form of the task statement, the command to be sent to the host system
to execute the new IRAF task may be any string.  For example, on a VMS host,
we might want to define the \fImail\fR task so that outgoing messages are
always composed in the editor.  This could be set up by adding the \fL/EDIT\fR
switch to the command sent to VMS:
.DS
\fLtask $mail = $mail/edit\fR
.DE
Foreign task statements which reference user-written Fortran programs often
refer to the program by its filename.  For the task to work regardless of the
current directory, either the full pathname of the executable file must be
given, or some provision must be made at the host command interpreter level
to ensure that the task can be found.
.PP
When a foreign task is called from the CL, the CL builds up the command string
to be sent to the host command interpreter by converting each command line
argument to a string and appending it to \fIhost_command_string\fR preceded
by a space.  This is the principal difference between the foreign task
interface and the low level OS escape facility: in the case of a foreign task,
the command line is fully parsed, permitting general expression evaluation,
i/o redirection, background execution, minimum match abbreviations, and so on.
.PP
In most cases this simple method of composing the command to be sent to the
host system is sufficient.  There are occasional cases, however, where it is
desirable to \fIembed\fR the command line arguments somewhere in the string
to be sent to the host system.  A special \fIargument substitution\fR notation
is provided for this purpose.  In this form of the task statement,
\fIhost_command_string\fR contains special symbols which are replaced by the
CL command line arguments to form the final host command string.
These special symbols are defined in the table below.

.TS
center;
c l.
$0	replaced by \fItaskname\fR
$1, $2, ..., $9	replaced by the indicated argument string
$\(**	replaced by the entire argument list
$(N)	use host equivalent of filename argument N (1-9 or \(**)
.TE

.PP
An example of this form of the task statement is the \fIfc\fR task discussed
in \(sc3.1.  As we noted earlier, \fIfc\fR is merely a front-end to the more
general IRAF HSI command/link utility \fIxc\fR.  In fact, \fIfc\fR is
implemented as a foreign task defined in the default \fIuser\fR package in
the \fLLOGIN.CL\fR file.  The task declaration used to define \fIfc\fR is
shown below.  The task statement shown is for UNIX; the VMS version is
identical except that the \fL-O\fR switch must be quoted else DCL will convert
it to lower case.  In general, foreign task statements are necessarily
machine dependent, since their function is to send a command to the host system.
.DS
\fLtask $fc = "$xc -h -O $\(** -limfort -lsys -lvops -los"\fR
.DE
The argument substitution facility is particularly useful when the host
command template consists of several statements to be executed by the
host command interpreter in sequence each time the CL foreign task is called.
In this case, a delimiter character of some sort is required to delimit
the host command interpreter statements.  Once again, this is host system
dependent, since the delimiter character to be used is defined by the syntax
of the host command interpreter.  On UNIX systems the command delimiter
character is semicolon (`\fB;\fR').  VMS DCL does not allow multiple
statements to be given on a single command line, but the IRAF interface
to DCL does, using the exclamation character (`\fB!\fR'), which is the
comment character in DCL.
.PP
The \fL$()\fR form of argument substitution is useful for foreign tasks
with one or more filename arguments.  The indicated argument or arguments
are taken to be IRAF virtual filenames, and are mapped into their host
filename equivalents to build up the host command string.  For example,
assume that we have an IMFORT task \fIphead\fR, the function of which is
to print the header of an image in FITS format on the standard output
(there really is such a program - look in \fLimfort$tasks/phead.f\fR).
We might declare the task as follows (assuming that \fIphead\fR means
something to the host system):
.DS
\fLtask $phead = "$phead $(*)"\fR
.DE
We could then call the new task from within the CL to list the header
of, for example, the standard test image \fLdev$pix\fR, and page the output:
.DS
\fLcl> phead dev$pix | page\fR
.DE
Or we could direct the output to the line printer:
.DS
\fLcl> phead dev$pix | lpr\fR
.DE
Filename translation is available for all forms of argument substitution
symbols, e.g., \fL$(1)\fR, \fL$(2)\fR, \fL$(\(**)\fR, and so on; merely
add the parenthesis.
.PP
It is suggested that new foreign task statements, if not typed in
interactively, be added to the \fIuser\fR package in your \fLLOGIN.CL\fR file,
so that the definitions are not discarded when you log out of the CL or exit
a package.  If you want to make the new tasks available to other IRAF users
they can be added to the \fIlocal\fR package by adding the task statements
to the file \fLlocal$tasks/local.cl\fR.  If this becomes unwieldy the
next step is to define a new package and add it to the system; this is not
difficult to do, but it is beyond the scope of this manual to explain how
to do so.

.NH 3
Example 1 Revisited
.PP
Now that we are familiar with the details of the foreign task statement,
it might be useful to review the examples of foreign task statements given
in \(sc2.1, which introduced the \fIplanck\fR task.  The UNIX example given
was as follows:
.DS
\fLcl> task $planck = $planck.e\fR
.DE
This is fine, but only provided the \fIplanck\fR task is called from the
directory containing the executable.  To enable the executable to be called
from any directory we can use a UNIX pathname instead, e.g.,
.DS
\fLcl> task $planck = $/usr/jones/iraf/tasks/planck.e\fR
.DE
Alternatively, one could place all such tasks in a certain directory, and
either define the pathname of the directory as a shell environment variable
to be referenced in the task statement, or include the task's directory in
the shell search path.  There are many other possibilities, of course, but
it would be inappropriate to enumerate them here.
.LP
The VMS example given earlier was the following:
.DS
\fLcl> task $planck = "$planck:==\\\\$\fIdisk\fP:[\fIdir\fP...]planck.exe!planck"\fR
.DE
The command string at the right actually consists of two separate DCL commands
separated by the VMS/IRAF DCL command delimiter `\fB!\fR'.  If we invent a
pathname for the executable, we can write down the the first command:
.DS
\fL$ planck :== $usr\\\\$2:[jones.iraf.tasks]planck.exe\fR
.DE
This is a DCL command which defines the new DCL foreign task \fIplanck\fR.
We could shorten the CL foreign task statement by moving the DCL declaration
to our DCL \fLLOGIN.COM\fR file; this has the additional benefit of allowing
the task to be called directly from DCL, but is not as self-contained.
If this were done the CL task statement could be shortened to the following.
.DS
\fLcl> task $planck = $foreign\fR
.DE
The same thing could be accomplished in Berkeley UNIX by defining a cshell
\fIalias\fR for the task in the user's \fL.cshrc\fR file.

.NH 2
Debugging IMFORT Programs
.PP
Programs written and called from within the IRAF environment can be debugged
using the host system debug facility without any inconvenience.  The details
of how to use the debugger are highly dependent upon the host system since
the debugger is a host facility, but a few examples should help the reader
understand what is involved.
.PP
Berkeley UNIX provides two debug tools, the assembly language debugger
\fIadb\fR and the source language debugger \fIdbx\fR.  Both are implemented
as UNIX tasks and are called from within the IRAF environment as tasks,
with the name of the program to be debugged as a command line argument
(this example assumes that \fIadb\fR is a defined foreign task):
.DS
\fLcl> adb planck.e\fR
.DE
The program is then run with a debugger command, passing any command line
arguments to the program as part of the debugger run-program command.
Programs do not have to be compiled in any special way to be debugged
with \fIadb\fR; programs should be compiled with \fIfc -x\fR to be debugged
with \fIdbx\fR.
.PP
In VMS, the debugger is not a separate task but rather a shareable image
which is linked directly into the program to be debugged.  To debug a program,
the program must first be linked with \fIfc -x\fR.  The program is then run
by simply calling it in the usual way from the CL, with any arguments given
on the command line.  When the program runs it comes up initially in the
debugger, and a debugger command (\fIgo\fR) is required to execute the user
program.  Note that if the program is run directly with \fLrun/debug\fR
there is no provision for passing an argument list to the task.

.NH 2
Calling IMFORT from Languages other than Fortran
.PP
Although our discussion and examples have concentrated exclusively on the
use of the IMFORT library in host Fortran programs, the library is in fact
language independent, i.e., it uses only low level, language independent
system facilities and can therefore be called from any language available
on the host system.  The method by which Fortran subroutines and functions
are called from another language, e.g., C or assembler, is highly machine
dependent and it would be inappropriate for us to go into the details here.
Note that \fIfc\fR may be used to compile and link C or assembler programs
as well as Fortran programs.

.NH 2
Avoiding Library Name Collisions
.PP
Any program which uses IMFORT is being linked against the main IRAF system
libraries, which together contain some thousands of external procedure names.
Only a few hundred of these are likely to be linked into a host program,
but there is always the chance that a user program module will have the
same external name as one of the modules in the IRAF libraries.
If such a library collision should occur, at best one would get an error
message from the linker, and at worst one would end up with a program
which fails mysteriously at run time.
.PP
At present there is no utility which can search a user program for externals
and cross check these against the list of externals in the IRAF system
libraries.  A database of external names is however available in the file
\fLlib$names\fR; this contains a sorted list of all the Fortran callable
external names defined by procedures in the \fIimfort\fR, \fIex\fR, \fIsys\fR,
\fIvops\fR, and \fIos\fR libraries (the \fIex\fR library is however not
searched when linking IMFORT programs).
.PP
The \fImatch\fR task may be used to check individual user external names
against the name list, or a host utility may be used for the same purpose.
For example, to determine if the module \fIsubnam\fR is present in any
of the IRAF system libraries:
.DS
\fLcl> match subnam lib$names\fR
.DE
The names database is also useful for finding the names of all the procedures
sharing a particular package prefix.  For example,
.DS
\fLcl> match "^cl" lib$names | table\fR
.DE
will find all the procedures whose names begin with the prefix "cl" and
print them as a table (the \fIlists\fR package must be loaded first).

.bp
.NH
The IMFORT Library
.PP
In this section we survey the procedures provided by the IMFORT interface,
grouped according to the function they perform.  There are currently four main
groups: the command line access procedures, the image access procedures,
the vector operators (VOPS), and a small binary file i/o package.  With the
exception of the VOPS procedures, all of the IMFORT routines were written
especially for IMFORT and are not called in standard IRAF programs.
The VOPS procedures are standard IRAF procedures, but are included in the
IMFORT interface because they are coded at a sufficiently low level that they
can be linked into any program, and they tend to be useful in image processing
applications such as IMFORT is designed for.
.PP
The ANSI Fortran-77 standard requires that all names in Fortran programs have
six or fewer characters.  To eliminate guesswork, the names of all the IMFORT
procedures are exactly six characters long and the names adhere to a
\fBnaming convention\fR.  The first one or two characters in each name
identify the package or group to which the procedure belongs, e.g.,
\fIcl\fR for the command line access package, \fIim\fR for the image
access package, and so on.  The package prefix is followed by the function name,
and lastly a datatype code identifying the datatype upon which the procedure
operates, in cases where multiple versions of the procedure are available for
a range of datatypes.
.DS
\fIpackage_prefix // function_code // type_suffix\fR
.DE
The type suffix codes have already been introduced in the examples.  They are
the same as are used throughout IRAF.  The full set is \fB[bcsilrdx]\fR, as
illustrated in the following table (not all are used in the IMFORT procedures).

.TS
center box;
cb s s s
ci | ci | ci | ci
c | l | c | l.
Standard IRAF Datatypes
_
suffix	name	code	typical fortran equivalent
=
b	bool	1	\fLLOGICAL\fR
c	char	2	\fLINTEGER\(**2\fR (non-ANSI)
s	short	3	\fLINTEGER\(**2\fR (non-ANSI)
i	int	4	\fLINTEGER\fR
l	long	5	\fLINTEGER\(**4\fR (non-ANSI)
r	real	6	\fLREAL\fR
d	double	7	\fLDOUBLE PRECISION\fR
x	complex	8	\fLCOMPLEX\fR
.TE
.PP
The actual mapping of IRAF datatypes into host system datatypes is machine
dependent, i.e., \fIshort\fR may not map into INTEGER\(**2 on all machines.
This should not matter since the datatype in which data is physically stored
internally is hidden from user programs by the IMFORT interface.
.PP
In cases where multiple versions of a procedure are available for operands
of different datatypes, a special nomenclature is used to refer to the class
as a whole.  For example,
.DS
\fLclarg[cird] (argno, [cird]val, ier)\fR 
.DE
denotes the set of four procedures \fIclargc, clargi, clargr\fR, and
\fIclargd\fR.  The datatype of the output operand (\fIcval, ival\fR, etc.)
must match the type specified by the procedure name.
.PP
With the exception of the low level binary file i/o procedures (BFIO),
all IMFORT procedures are implemented as subroutines rather than functions,
for reasons of consistency and to avoid problems with mistyping of undeclared
functions by the Fortran compiler.

.NH 2
Command Line Access
.PP
The command line access procedures are used to decode the arguments present
on the command line when the IMFORT program was invoked.  This works both
when the program is called from the IRAF CL, and when the program is called
from the host system command interpreter.  The command line access procedures
are summarized in Figure 4, below.

.TS
center;
n.
\fLclnarg (\&nargs)\fR
\fLclrawc (\&outstr, ier)\fR
\fLclarg[cird] (\&argno, [cird]val, ier)\fR
.TE
.sp
.ce
Figure 4.  Command Line Access Procedures

.PP
The \fIclnarg\fR procedure returns the number of command line arguments;
zero is returned if an error occurs or if there were no command line arguments.
The \fIclargc\fR, \fIclargi\fR, etc., procedures are used to fetch and decode
the individual arguments; \fIclargc\fR returns a character string, \fIclargi\fR
returns an integer, and so on.  A nonzero \fIier\fR status indicates either
that the command line did not contain the indexed argument, or that the
argument could not be decoded in the manner specified.  Character string
arguments must be quoted on the command line if they contain any blanks or
tabs, otherwise quoting is not necessary.  The rarely used \fIclrawc\fR
procedure returns the entire raw command line as a string.

.NH 2
Image Access
.PP
The image access procedures form the bulk of the IMFORT interface.  There are
three main categories of image access procedures, namely, the general image
management procedures (open, close, create, get size, etc.), the header access
procedures (used to get and put the values of header keywords), and the pixel
i/o procedures, used to read and write image data.
.PP
IMFORT currently supports images of up to three dimensions,
of type short-integer or real.
There is no builtin limit on the size of an image, although
the size of image a particular program can deal with is normally limited by
the size of a statically allocated buffer in the user program.  IMFORT does
not map IRAF virtual filenames, hence host dependent names must be used when
running a program which uses IMFORT.
.PP
IMFORT currently supports only the OIF image format, and images must be
of type short-integer or real.  Since normal IRAF programs support images of
up to seven disk datatypes with a dimensionality of up to seven, as well as
completely different image formats than that expected by IMFORT (e.g., STF),
if you are not careful IRAF can create images which IMFORT programs cannot
read (don't omit the error checking!).  In normal use, however,
types short-integer and real are by far the most common and images with
more than two dimensions are rare, so these are not expected to be serious
limitations.

.NH 3
General Image Access Procedures
.PP
The general image access and management procedures are listed in Figure 5.
An image must be opened with \fIimopen\fR or \fIimopnc\fR before header access
or pixel i/o can occur.  The image open procedures return an
\fIimage descriptor\fR (an integer magic number) which uniquely identifies
the image in all subsequent accesses until the image is closed.
When the operation is completed, an image must be closed with \fIimclos\fR to
flush any buffered output, update the image header, and free any resources
associated with the image descriptor.  The maximum number of images which
can be open at any one time is limited by the maximum number of open file
descriptors permitted by the host operating system.
.PP
New images are created with \fIimopnc\fR and \fIimcrea\fR.  The \fIimopnc\fR
procedure creates a new copy of an existing image, copying the header of
the old image to the new image but not the data.  The new copy image must
be the same size and datatype as the old image.  For complete control over
the attributes of a new image the \fIimcrea\fR procedure must be used.
The \fIimopnc\fR operation is equivalent to an \fIimopen\fR followed by an
\fIimgsiz\fR to determine the size and datatype of the old image, followed by
an \fIimcrea\fR to create the new image, followed by an \fIimhcpy\fR to copy
the header of the old image to the new image and then two \fIimclos\fR calls
to close both images.
.PP
Note that \fIimgsiz always returns seven elements in the output array axlen\fR,
regardless of the actual dimensionality of the image; this is so that current
programs will continue to work in the future if IMFORT is extended to support
images of dimensionality higher than three.  Images may be deleted with
\fIimdele\fR, or renamed with \fIimrnam\fR; the latter may also be used to
move an image to a different directory.  The \fIimflsh\fR procedure is used
to flush any buffered output pixel data to an image opened for writing.

.TS
center;
n.
\fLimopen (\&image, acmode, im, ier)      \fRacmode: 1=RO,3=RW
\fLimopnc (\&nimage, oim, nim, ier)       \fRacmode: always RW
\fLimclos (\&im, ier)\fR

\fLimcrea (\&image, axlen, naxis, dtype, ier)\fR
\fLimdele (\&image, ier)\fR
\fLimrnam (\&oldnam, newnam, ier)\fR

\fLimflsh (\&im, ier)\fR
\fLimgsiz (\&im, axlen, naxis, dtype, ier)\fR
\fLimhcpy (\&oim, nim, ier)\fR
\fLimpixf (\&im, pixfd, pixfil, pixoff, szline, ier)\fR
.TE
.sp
.ce
Figure 5.  General Image Access Procedures

.PP
The \fIimpixf\fR procedure may be used to obtain the physical attributes
of the pixel file, i.e., the pixel file name, the one-indexed \fIchar\fR
offset to the first pixel, and the physical line length of an image as stored
in the pixel file (the image lines may be aligned on device block boundaries).
These parameters may be used to bypass the IMFORT pixel i/o procedures to
directly access the pixels if desired (aside from the blocking of lines to
fill device blocks, the pixels are stored as in a Fortran array).
The BFIO file descriptor of the open pixel file is also returned, allowing
direct access to the pixel file via BFIO if desired.  If lower level (e.g.,
host system) i/o facilities are to be used, \fIbfclos\fR or \fIimclos\fR
should be called to close the pixel file before reopening it with the foreign
i/o system.
.PP
Direct access to the pixel file is not recommended since it makes a program
dependent upon the details of how the pixels are stored on disk; such a
program may not work with future versions of the IMFORT interface, nor with
implementations of the IMFORT interface for different (non-OIF) physical image
storage formats.  Direct access may be warranted when performing a minimum
modification hack of an old program to make it work in the IRAF environment,
or in applications with unusually demanding performance requirements,
where the (usually negligible) overhead of the BFIO buffer is unacceptable.
Note that in many applications, the reduction in disk accesses provided by
the large BFIO buffer outweighs the additional cpu cycles required for memory
to memory copies into and out of the buffer.

.NH 3
Image Header Keyword Access
.PP
The image header contains a small number of standard fields plus an arbitrary
number of user or application defined fields.  Each image has its own header
and IMFORT does not in itself make any association between the header parameters
of different images.  The header access procedures are summarized in Figure 6.
Note that the \fIimgsiz\fR procedure described in the previous section is the
most convenient way to obtain the size and datatype of an open image, although
the same thing can be achieved by a series of calls to obtain the values of
the individual keywords, using the procedures described in this section.

.TS
center;
n.
\fLimacck (\&im, keyw, ier)\fR
\fLimaddk (\&im, keyw, dtype, comm, ier)\fR
\fLimdelk (\&im, keyw, ier)\fR
\fLimtypk (\&im, keyw, dtype, comm, ier)\fR

\fLimakw[bcdir] (\&im, keyw, [bcdir]val, comm, ier)\fR
\fLimgkw[bcdir] (\&im, keyw, [bcdir]val, ier)\fR
\fLimpkw[bcdir] (\&im, keyw, [bcdir]val, ier)\fR

\fLimokwl (\&im, patstr, sortit, kwl, ier)\fR
\fLimgnkw (\&kwl, outstr, ier)\fR
\fLimckwl (\&kwl, ier)\fR
.TE
.sp
.ce
Figure 6.  Image Header Access Procedures

.PP
Both the standard and user defined header parameters may be accessed via the
procedures introduced in this section.  The \fIimacck\fR procedure tests for
the existence of the named keyword, returning a zero \fIier\fR if the keyword
exists.  New keywords may be added to the image header with \fIimaddk\fR,
and old keywords may be deleted with \fIimdelk\fR.  The datatype of a keyword
may be determined with \fIimtypk\fR.  The attributes of a keyword are its
name, datatype, value, and an optional comment string describing the
significance of the parameter.  The comment string is normally invisible
except when the header is listed, but may be set when a new keyword is added
to the header, or fetched with \fIimtypk\fR.
.PP
The most commonly used procedures are likely to be the \fIimgkw\fR and
\fIimpkw\fR families of procedures, used to get and put the values of named
keywords; these procedures require that the keyword already be present in
the header.  The \fIimakw\fR procedures should be used instead of the
\fIimpkw\fR procedures if it is desired that a keyword be automatically added
to the header if not found, before setting the new value.  Automatic datatype
conversion is performed if the requested datatype does not match the actual
datatype of the keyword.
.PP
The \fIkeyword list\fR package is the only way to obtain information from
the header without knowing in advance the names of the header keywords.
The \fIimokwl\fR procedure opens a keyword list consisting of all header
keywords matching the given pattern, returning a \fIlist descriptor\fR to
be used as input to the other procedures in the package.  Successive
keyword \fInames\fR are returned in calls to \fIimgnkw\fR; a nonzero
\fIier\fR is returned when the end of the list is reached.  The keyword
name is typically used as input to other procedures such as \fIimtypk\fR
or one of the \fIimgkw\fR procedures to obtain further information about
the keyword.  A keyword list should be closed with \fIimckwl\fR when it is
no longer needed to free system resources associated with the list descriptor.

.TS
center box;
cb s s
ci | ci | ci
l | c | l.
Standard Image Header User Keywords
_
name	datatype	description
=
naxis	int	number of axes (dimensionality)
naxis[1:3]	int	length of each axis, pixels
pixtype	int	pixel datatype
datamin	real	minimum pixel value
datamax	real	maximum pixel value
ctime	int	image creation time
mtime	int	image modification time
limtime	int	time min/max last updated
title	string	image title string (for plots etc.)
.TE

.PP
The keyword list pattern string follows the usual IRAF conventions; some
useful patterns are "\(**", which matches the entire header, and "i_", which
matches only the standard header keywords (the standard header keywords are
really named "i_naxis", "i_pixtype", etc., although the "i_" may be omitted
in most cases).  A pattern which does not include any pattern matching
metacharacters is taken to be a prefix string, matching all keywords whose
names start with the pattern string.
.PP
An image must be opened with read-write access for header updates to have
any effect.  An attempt to update a header without write permission will
not produce an error status return until \fIimclos\fR is called to update
the header on disk (and close the image).

.NH 3
Image Pixel Access
.PP
The IMFORT image pixel i/o procedures are used to get and put entire image
lines to N-dimensional images, or to get and put N-dimensional subrasters
to N-dimensional images.  In all cases the caller supplies a buffer into
which the pixels are to be put, or from which the pixels are to be taken.
The pixel i/o procedures are summarized in Figure 7.
.PP
As shown in the figure, there are four main classes of pixel i/o procedures,
the get-line, put-line, get-section, and put-section procedures.  The get-line
and put-line procedures are special cases of the get/put section procedures,
provided for programming convenience in the usual line by line sequential
image operator (they are also slightly more efficient than the subraster
procedures for line by line i/o).  It is illegal to reference out of bounds
and \fIi1\fR must be less than or equal to \fIi2\fR (IMFORT will not flip
lines); the remaining subscripts may be swapped if desired.  Access may be
completely random if desired, but sequential access (in storage order) implies
fewer buffer faults and is more efficient.

.KS
.TS
center;
n.
\fLim[gp]l1[rs] (\&im, buf, ier)\fR
\fLim[gp]l2[rs] (\&im, buf, lineno, ier)\fR
\fLim[gp]l3[rs] (\&im, buf, lineno, bandno, ier)\fR
\fLim[gp]s1[rs] (\&im, buf, i1, i2, ier)\fR
\fLim[gp]s2[rs] (\&im, buf, i1, i2, j1, j2, ier)\fR
\fLim[gp]s3[rs] (\&im, buf, i1, i2, j1, j2, k1, k2, ier)\fR
.TE
.sp
.ce
Figure 7.  Image Pixel I/O Procedures
.KE

.PP
Type short and type real versions of each i/o procedure are provided.
The type real procedures may be used to access images of either type short
or type real, with automatic datatype conversion being provided if the disk
and program datatypes do not match.  The type short-integer i/o procedures
may only be used with type short images.
.PP
The user who is familiar with the type of image i/o interface which maps
the pixel array into virtual memory may wonder why IMFORT uses the more old
fashioned buffered technique.  There are two major reasons why this approach
was chosen.  Firstly, the virtual memory mapping technique, in common use on
VMS systems, is \fInot portable\fR.  On a host which does not support the
mapping of file segments into paged memory, the entire image must be copied
into paged memory when the image is opened, then copied again when the image
operation takes place, then copied once again from memory to disk when the
image is closed.  Needless to say this is very inefficient, particularly for
large images, and some of our applications deal with images 2048 or even 6000
pixels square.
.PP
Even on a machine that supports mapping of file segments into memory, mapped
access will probably not be efficient for sequential access to large images,
since it causes the system to page heavily; data pages which will never be
used again fill up the system page caches, displacing text pages that must
then be paged back in.  This happens on even the best systems, and on a system
that does not implement virtual memory efficiently, performance may suffer
greatly.
.PP
A less obvious reason is that mapping the image directly into memory violates
the principle of \fIdata independence\fR, i.e., a program which uses this
type of interface has a builtin dependence on the particular physical image
storage format in use when the program was developed.  This rules out even
such simple interface features as automatic datatype conversion, and prevents
the expansion of the interface in the future, e.g., to provide such attractive
features as an image section capability (as in the real IRAF image interface),
network access to images stored on a remote node, support for pixel storage
schemes other than line storage mode (e.g., isotropic mappings or sparse image
storage), and so on.  
.PP
The majority of image operations are either sequential whole-image operations
or operations upon subrasters, and are just as easily programmed with a
buffered interface as with a memory mapped interface.  The very serious
drawbacks of the memory mapped interface dictate that it not be used except
in special applications that must randomly access individual pixels in an
image too large to be read in as a subraster.

.NH 2
Error Handling
.PP
The IMFORT error handling mechanism is extremely simple.  All procedures in
which an error condition can occur return a nonzero \fIier\fR error code
if an error occurs.  The value of \fIier\fR identifies which of many possible
errors actually occurred.  These error codes may be converted into error
message strings with the following procedure:
.DS
\fLimemsg (\&ier, errmsg)\fR
.DE
It is suggested that every main program contain an error handling section at
the end of the program which calls \fIimemsg\fR and halts program execution
with an informative error message, as in the examples in \(sc2.
This is especially helpful when debugging new programs.

.NH 2
Vector Operators
.PP
The vector operators (VOPS) package is a subroutine library implementing
a large number of primitive operations upon one dimensional vectors of any
datatype.  Some of the operations implemented by the VOPS routines are
non-trivial to implement, in which case the justification for a library
subroutine is clear.  Even in the simplest cases, however, the use of a
VOPS procedure is advantageous because it provides scope for optimizing
all programs which use the VOPS operator, without having to modify the
calling programs.  For example, if the host machine has vector hardware
or special machine instructions (e.g., the block move and bitfield instructions
of the VAX), the VOPS operator can be optimized in a machine dependent way
to take advantage of the special capabilities of the hardware, without
compromising the portability of the applications software using the procedure.
.PP
The VOPS procedures adhere to the naming convention described in \(sc4.
The package prefix is \fIa\fR, the function code is always three characters,
and the remaining one or two characters define the datatype or types upon
which the procedure operates.  For example, \fIaaddr\fR performs a vector
add upon type real operands.  If the character \fIk\fR is added to the
three character function name, one of the operands will be a scalar.
For example, \fIaaddkr\fR adds a scalar to a vector, with both the scalar
and the vector being of type real.
.PP
Most vector operators operate upon operands of a single datatype: one notable
exception is the \fIacht\fR (change datatype) operator, used to convert a
vector from one datatype to another.  For example, \fIachtbi\fR will unpack
each byte in a byte array into an integer in the output array, providing a
capability that cannot be implemented in portable Fortran.  Any datatype
suffix characters may be substituted for the \fIbi\fR, to convert a vector
from any datatype to any other datatype.
.PP
In general, there are are three main classes of vector operators, the
\fIunary\fR operators, the \fIbinary\fR operators, and the \fIprojection\fR
operators.  The unary operators perform some operation upon a single input
vector, producing an output vector as the result.  The binary operators
perform some operation upon two input vectors, producing an output vector
as the result.  The projection operators compute some function of a single
input vector, producing a scalar function value (rather than a vector) as
the result.  Unary operators typically have three arguments, binary
operators four, and projection operators two arguments and one output
function value.  For example, \fIaabsi\fR is the unary absolute value
vector operator, type integer (here, \fIa\fR is the input vector, \fIb\fR
is the output vector, and \fInpix\fR is the number of vector elements):
.DS
\fLaabsi (a, b, npix)\fR
.DE
A typical example of a binary operator is the vector add operator, \fIaaddr\fR.
Here, \fIa\fR and \fIb\fR are the input vectors, and \fIc\fR is the output
vector:
.DS
\fLaaddr (a, b, c, npix)\fR
.DE
In all cases except where the output vector contains fewer elements than one
of the input vectors, the output vector may be the same as one of the input
vectors.  A full range of datatypes are provided for each vector operator,
except that there are no boolean vector operators (integer is used instead),
and \fIchar\fR and \fIcomplex\fR are only partially implemented, since they
are not sensible datatypes for many vector operations.  In any case, the VOPS
\fIchar\fR is the SPP char and should be avoided in Fortran programs.
.PP
Once these rules are understood, the calling sequence of a particular VOPS
operator can usually be predicted with little effort.  The more complex
operators, of course, may have special arguments, and some study is typically
required to determine their exact function and how they are used.  A list of
the VOPS operators currently provided is given below (the datatype suffix
characters must be added to the names shown to form the full procedure names).

.TS
center;
n.
aabs -\& Absolute value of a vector
aadd -\& Add two vectors
aaddk -\& Add a vector and a scalar
aand -\& Bitwise boolean AND of two vectors
aandk -\& Bitwise boolean AND of a vector and a scalar
aavg -\& Compute the mean and standard deviation of a vector
abav -\& Block average a vector
abeq -\& Vector equals vector
abeqk -\& Vector equals scalar
abge -\& Vector greater than or equal to vector
abgek -\& Vector greater than or equal to scalar
abgt -\& Vector greater than vector
abgtk -\& Vector greater than scalar
able -\& Vector less than or equal to vector
ablek -\& Vector less than or equal to scalar
ablt -\& Vector less than vector
abltk -\& Vector less than scalar
abne -\& Vector not equal to vector
abnek -\& Vector not equal to scalar
abor -\& Bitwise boolean OR of two vectors
abork -\& Bitwise boolean OR of a vector and a scalar
absu -\& Block sum a vector
acht -\& Change datatype of a vector
acjgx -\& Complex conjugate of a complex vector
aclr -\& Clear (zero) a vector
acnv -\& Convolve two vectors
acnvr -\& Convolve a vector with a real kernel
adiv -\& Divide two vectors
adivk -\& Divide a vector by a scalar
adot -\& Dot product of two vectors
advz -\& Vector divide with divide by zero detection
aexp -\& Vector to a real vector exponent
aexpk -\& Vector to a real scalar exponent
afftr -\& Forward real discrete fourier transform
afftx -\& Forward complex discrete fourier transform
aglt -\& General piecewise linear transformation
ahgm -\& Accumulate the histogram of a series of vectors
ahiv -\& Compute the high (maximum) value of a vector
aiftr -\& Inverse real discrete fourier transform
aiftx -\& Inverse complex discrete fourier transform
aimg -\& Imaginary part of a complex vector
alim -\& Compute the limits (minimum and maximum values) of a vector
alln -\& Natural logarithm of a vector
alog -\& Logarithm of a vector
alov -\& Compute the low (minimum) value of a vector
altr -\& Linear transformation of a vector
alui -\& Vector lookup and interpolate (linear)
alut -\& Vector transform via lookup table
amag -\& Magnitude of two vectors (sqrt of sum of squares)
amap -\& Linear mapping of a vector with clipping
amax -\& Vector maximum of two vectors
amaxk -\& Vector maximum of a vector and a scalar
amed -\& Median value of a vector
amed3 -\& Vector median of three vectors
amed4 -\& Vector median of four vectors
amed5 -\& Vector median of five vectors
amgs -\& Magnitude squared of two vectors (sum of squares)
amin -\& Vector minimum of two vectors
amink -\& Vector minimum of a vector and a scalar
amod -\& Modulus of two vectors
amodk -\& Modulus of a vector and a scalar
amov -\& Move (copy or shift) a vector
amovk -\& Move a scalar into a vector
amul -\& Multiply two vectors
amulk -\& Multiply a vector and a scalar
aneg -\& Negate a vector (change the sign of each pixel)
anot -\& Bitwise boolean NOT of a vector
apkx -\& Pack a complex vector given the real and imaginary parts
apol -\& Polynomial evaluation
apow -\& Vector to an integer vector power
apowk -\& Vector to an integer scalar power
arav -\& Mean and standard deviation of a vector with pixel rejection
arcp -\& Reciprocal of a scalar and a vector
arcz -\& Reciprocal with detection of divide by zero
arlt -\& Vector replace pixel if less than scalar
argt -\& Vector replace pixel if greater than scalar
asel -\& Vector select from two vectors based on boolean flag vector
asok -\& Selection of the Kth smallest element of a vector
asqr -\& Square root of a vector
asrt -\& Sort a vector in order of increasing pixel value
assq -\& Sum of squares of a vector
asub -\& Subtract two vectors
asubk -\& Subtract a scalar from a vector
asum -\& Sum of a vector
aupx -\& Unpack the real and imaginary parts of a complex vector
awsu -\& Weighted sum of two vectors
awvg -\& Mean and standard deviation of a windowed vector
axor -\& Bitwise boolean XOR (exclusive or) of two vectors
axork -\& Bitwise boolean XOR (exclusive or) of a vector and a scalar
.TE

.PP
A non-trivial example of the use of vector operators is the case of bilinear
interpolation on a two dimensional image.  The value of each pixel in the
output image is a linear sum of the values of four pixels in the input image.
The obvious solution is to set up a do-loop over the pixels in each line of
the output image, computing the linear sum over four pixels from the input
image for each pixel in the output line; this is repeated for each line in the
output image.
.PP
The solution using the VOPS operators involves the \fIalui\fR (vector look up
and interpolate) and \fIawsu\fR (weighted sum) vector operators.  A lookup table
defining the X-coordinate in the input image of each pixel in a line of the
output image is first generated.  Then, for each line of the output image,
the two lines from the input image which will contribute to the output image
line are extracted.  \fIAlui\fR is used to interpolate each line in X, then
\fIawsu\fR is used to form the weighted sum to interpolate in the Y direction.
This technique is especially efficient when bilinear interpolation is being
used to expand the image, in which case the \fIalui\fR interpolated X-vectors,
for example, are computed once but then used to generate several lines of
the output image by taking the weighted sum, a simple and fast operation.
When moving sequentially up through the image, the high X-vector becomes the
low X-vector for the next pair of input lines, hence only a single call to
\fIalui\fR is required to set up the next region.
.PP
The point of this example is that many or most image operations can be
expressed in terms of primitive one dimensional vector operations,
regardless of the dimensionality of the image being operated upon.
The resultant algorithm will often run more efficiently even on a conventional
scalar machine than the equivalent nonvectorized code, and will probably run
efficiently without modification on a vector machine.
.PP
Detailed specification sheets (manual pages) are not currently available for
the VOPS procedures.  A summary of the calling sequences is given in the file
\fLvops$vops.syn\fR, which can be paged or printed by that name while in the
CL, assuming that the system has not been stripped and that the sources are
still on line.  The lack of documentation is really not a problem for these
operators, since they are all fairly simple, and it is easy to page the source
file (in the \fIvops\fR directory) to determine the exact calling sequence.
For example, to examine the source for \fIawsu\fR, type
.DS
\fLcl> page vops$awsu.gx\fR
.DE
to page the generic source, regardless of the specific datatype of interest.
If you have trouble deciphering the generic source,
use \fLxc -f file.x\fR to produce the Fortran translation
of one of the type specific files in the subdirectories
\fLvops$ak\fR and \fLvops$lz\fR.

.NH 2
Binary File I/O (BFIO)
.PP
The IMFORT binary file i/o package (BFIO) is a small package, written
originally as an internal package for use by the IMFORT image i/o routines
for accessing header and pixel files (the VOS FIO package could not be used
in IMFORT without linking the entire IRAF/VOS runtime system into the Fortran
program).  Despite its original conception as an internal package, the package
provides a useful capability and is portable, hence has been included in the
IMFORT interface definition.  Nonetheless, the user should be warned that BFIO
is a fairly low level interface and some care is required to use it safely.
If other suitable facilities are available it may be better to use those,
although few interfaces will be found which are simpler or more efficient
than BFIO for randomly accessing pre-existing or preallocated binary files.
.PP
The principal capability provided by BFIO is the ability to randomly access
a binary file, reading or writing an arbitrary number of char-units of storage
at any (one-indexed) char offset in the file.  The file itself is a non-record
structured file containing no embedded record manager information,
hence is suitable for access by any program, including non-Fortran programs,
and for export to other machines (this is usually not the case with a Fortran
unformatted direct access file).  Unlike the mainline IMFORT procedures,
many of the BFIO procedures are integer functions returning a positive count
value if the operation is successful (e.g., the number of char units of storage
read or written), or a negative value if an error occurs.  Zero is returned
for a read at end of file.

.TS
center;
n.
\fLbfaloc (\&fname, nchars, status)\fR
\fLfd = bfopen (\&fname, acmode, advice)   \fRacmode: 1=RO,3=RW,5=NF
\fLbfclos (\&fd, status)              \fRadvice: 1=random,2=seq

\fLnchars = bfread (\&fd, buf, nchars, offset)\fR
\fLnchars = bfwrit (\&fd, buf, nchars, offset)\fR

\fLnchars = bfbsiz (\&fd)\fR
\fLnchars = bffsiz (\&fd)\fR
\fLchan = bfchan (\&fd)\fR
\fLstat = bfflsh (\&fd)\fR
.TE
.sp
.ce
Figure 8.  Low Level Binary File I/O Procedures

.PP
BFIO binary files may be preallocated with \fIbfaloc\fR, or created with
\fIbfopen\fR and then initialized by writing at the end of file.
Preallocating a file is useful when the file size is known in advance, e.g.,
when creating the pixel file for a new image.  The contents of a file
allocated with \fIbfaloc\fR are uninitialized.  To extend a file by writing
at the end of file the file size must be known; the file size may be obtained
by calling \fIbffsiz\fR on the open file.
.PP
Before i/o to a file can occur, the file must be opened with \fIbfopen\fR.
The \fIbfopen\fR procedure returns as its function value an integer
\fIfile descriptor\fR which is used to refer to the file in all subsequent
accesses until the file is closed with \fIbfclos\fR.  Binary data is read
from the file with \fIbfread\fR, and written to the file with \fIbfwrit\fR.
Any amount of data may be read or written in a single call to \fIbfread\fR
or \fIbfwrit\fR.  All user level i/o is synchronous and data is buffered
internally by BFIO to minimize disk transfers and provide for the blocking
and deblocking of data into device blocks.  Any buffered output data may be
flushed to disk with \fIbfflsh\fR.  The function \fIbfchan\fR returns the
descriptor of the raw i/o channel as required by the IRAF binary file driver.
.PP
BFIO manages an internal buffer, necessary for efficient sequential i/o and
to hide the device block size from the user program.  Larger buffers are
desirable for sequential i/o on large files; smaller buffers are best for
small files or for randomly accessing large files.  The buffer size may be
set at \fIbfopen\fR time with the \fIadvice\fR parameter.  An \fIadvice\fR
value of 1 implies random access and causes a small buffer to be allocated;
a value of 2 implies sequential access and causes a large buffer to be
allocated.  Any other value is taken to be the actual buffer size in chars,
but care must be used since the value specified must be some multiple of the
device block size, and less than the maximum transfer size permitted by the
kernel file driver.  Note that when writing at end of file, the full contents
of the internal buffer will be written, even if the entire buffer contents
were not written into in a \fIbfwrit\fR call.  The buffer size in chars is
returned by \fIbfbsiz\fR.
.PP
Since BFIO is a low level interface, the file offset must always be specified
when reading from or writing to the file, even when the file is being accessed
sequentially.  Contrary to what one might think, file offsets are one-indexed
in the Fortran tradition, and are specified in units of \fIchars\fR.
Do not confuse \fIchar\fR with the Fortran \fLCHARACTER\fR; \fIchar\fR is the
fundamental unit of storage in IRAF, the smallest datum which can be accessed
as an integer quantity with the host Fortran compiler, normally
\fLINTEGER\(**2\fR (16 bits or two bytes on all current IRAF hosts).

.bp
.SH
Appendix:  Manual Pages for the Imfort Procedures
.PP
This section presents the ``manual pages'' for the IMFORT and BFIO procedures.
The manual pages present the exact technical specifications of each procedure,
i.e., the procedure name and arguments (not necessarily obvious in the case of
a typed family of procedures), the datatypes and dimensions of the arguments,
and a precise description of the operation of the procedure.
Each procedure is presented on a separate page for ease of reference.
.PP
The following conventions have been devised to organize the information
presented in this section:
.RS
.IP \(bu
The manual pages are presented in alphabetical order indexed by the procedure
name.
.IP \(bu
A single manual page is used to present an entire family of procedures which
differ only in the datatype of their primary operand.  The name on the manual
page is the generic name of the family, e.g., \fIclargi\fR, \fIclargr\fR, etc.,
are described in the manual page \fIclarg\fR.
.IP \(bu
In some cases it makes sense to describe several related procedures with a
single manual page.  An example is the keyword-list package, consisting of
the procedures \fIimokwl\fR, \fIimgnkw\fR, and \fIimckwl\fR.  In such a case,
since the procedures have different names the manual page for the group is
duplicated for each procedure in the group, so that the user will not have
to guess which name the manual page is filed under.
.IP \(bu
The \fIsynopsis\fR section of each manual page defines the calling sequence of
each procedure, the datatypes and dimensions of the arguments, and notes
whether each argument is an input argument (\fL#I\fR) or an output argument
(\fL#O\fR).
.IP \(bu
The \fIreturn value\fR section describes the conditions required for
successful execution of the procedure, normally indicated by a zero status
in \fIier\fR.  A symbolic list of the possible error codes is also given.
The numeric values of these error codes are defined in \fLimfort$imfort.h\fR
and in \fLlib$syserr.h\fR, but the exact numeric codes should be used only for
debugging purposes or passed on to the \fIimemsg\fR procedure to get the error
message string.  The numeric error codes are likely to change in future versions
of the interface hence their values should not be "wired into" programs.
.RE
.PP
Manual pages for the VOPS procedures are not included since VOPS is not really
part of the IMFORT interface, and it is not yet clear if the VOPS procedures
are complex enough to justify the production of individual manual pages.