.help "task,redefine" Apr87 language
.ih
NAME
.nf
task     -- define a new IRAF task
redefine -- redefine an IRAF task
.fi
.ih
USAGE
.nf
task     t1 [t2 ...] = tfile
redefine t1 [t2 ...] = tfile
.fi
.ih
PARAMETERS
.ls t1, t2, ...
The names of the new logical tasks.  The task name should be prefixed by a $
if the task has no parameter file.  An optional extension should be appended
if either the standard input or output of the task is a binary stream, rather
than text.  For example, "$mytask.tb" denotes a task with no parameter file,
a text standard input, and a binary standard output.
.le
.ls tfile
The name of the file to be executed or interpreted to run the task.
The type of the task is determined by the file extension.  An ".e" extension
indicates an executable task, while ".cl" indicates a CL script task or
procedure.  The \fItfile\fR string is prefixed by a $ to define a
\fIforeign task\fR (see the discussion below).
.le
.ih
DESCRIPTION
The \fItask\fR statement defines a new task to the CL, and is required before
the task can be run from the CL.  The new task is added to the "current
package", i.e., the package that is listed when "?" is entered.  Any task
definitions made since the current package was entered will be discarded
when the package is exited.

In addition to defining a new task, the \fItask\fR statement defines the
type and attributes of the new task.  Three types of tasks can be defined:
script (.cl), executable (.e), and foreign ($...).  A task is assumed to
have a parameter file ("taskname.par", in the same directory as \fItfile\fR),
unless the taskname is explicitly prefixed by a $.  A suffix or extension
may optionally be added to the task name to indicate whether the input and
output streams are text or binary.  The default is text, meaning that if
output (or input) is redirected to a file, the file will be opened as a
text file.

The \fIforeign task\fR facility allows host system tasks, e.g., host utilities
or user written Fortran or C programs, to be called from the CL as if they
were regular IRAF tasks.  The command line of a foreign task is parsed
like that of any other task (and unlike an OS escape), allowing expression
evaluation, i/o redirection, and background job submission.  The difference
between a regular IRAF task and a foreign task is that the foreign tasks have
little or no access to IRAF facilities, are usually machine dependent
(and programs which use them are machine dependent), and cannot be cached.
Nonetheless the foreign task facility is very useful for personalizing and
extending the IRAF environment with a minimum of effort.

The \fItask\fR statement includes facilities for defining how the host system
argument list for a foreign task will be built when the task is called from
the CL.  The simplest form of the foreign task statement is the following:

	task [$]taskname = "$host_command_prefix"

where \fIhost_command_prefix\fR is the first part of the command string to be
passed to the host system.  Any command line arguments are simply tacked onto
the end of this string, delimited by blanks.

If this is insufficient then argument substitution may be used to define how
the argument list is to be built up.  The macro \fB$N\fR denotes argument N
from the CL command line, with the first argument being number 1.  The macro
\fB$0\fR is a special case, and is replaced the name of the task being
executed.  Likewise, \fB$*\fR denotes all arguments.  If the character
following the $ is enclosed in parenthesis, the corresponding argument string
will be treated as an IRAF virtual filename, with the equivalent host system
filename being substituted for use in the host command.  Any other character
sequences are passed on unchanged.  The argument substitution macros are
summarized in the table below.

.ks
.nf
	$0		task name
	$N		argument N
	$*		all arguments
	$(...)		host system filename translation of "..."
.fi
.ke

When a task is invoked, an executable is run by starting an attached
sub-process, while a script is run by starting a new level of the CL
with its standard input set to the script file.

An executable image may contain any number of executable CL tasks, hence it
can be pointed to by multiple task names or in multiple \fItask\fR statements.
A script file can only contain one script task.

\fIRedefine\fR has the same syntax as the \fItask\fR command, but all the
task names must already be defined in the current package.  It is often
useful after misspelling the task file name in a task command.
.ih
EXAMPLES
1. Call up the editor to create a new program (task) mytask.x.  Compile
the new program.  Declare it using the task statement and then run it.

.nf
	cl> edit mytask.x			# edit
	cl> xc mytask.x				# compile & link
	cl> task $mytask = mytask.e		# define task
	cl> mytask arg1 arg2			# run it
.fi

2. Define a script task with associated parameter file (if the script is
a \fIprocedure\fR, the parameter file is omitted since procedure scripts
always have defined parameters).

	cl> task myscript = myscript.cl

3. Define the four new tasks implot, graph, showcap, and gkiextract.
All have parameter files except showcap.  The gkiextract task has a
binary output stream.  All tasks are executable and are stored in the
executable file "plot$x_plot.e".  Note the use of comma argument
delimiters in this example; this is a compute mode example as would
be found in a package script task.

.nf
	task	implot,			# compute mode syntax
		graph,
		$showcap,
		gkiextract.tb	= "plot$x_plot.e"
.fi

4. Make the listed UNIX programs available in the IRAF environment as
foreign tasks.  None of the tasks has a parameter file.  The "$foreign"
declares the tasks as foreign, and indicates that the IRAF task name
is the same as the host system task name.

	cl> task $ls $od $rlogin = $foreign

5. Define a couple of foreign tasks for VMS, where the command to be sent
to VMS is not the same as the IRAF task name.

.nf
	cl> task $run	= $run/nodebug
	cl> task $debug = $run/debug
	cl> task $top	= "$show proc/topcpu"
.fi
.ih
BUGS
The distinction between command and compute mode syntax can be confusing.
When defining tasks in your login.cl or in a package script task, use
compute mode, with commas between the arguments and all strings quoted
(there are plenty of examples in the system).  When typing in \fItask\fR
statements interactively, use command mode.  If you forget and leave in
the commas, they will be assumed to be part of the task name, causing the
following error message when the task is run:

	ERROR: IRAF Main: command syntax error
.ih
SEE ALSO
prcache, flprcache, package
.endhelp
