redefine: Redefine a task

Package: language

Usage

task     t1 [t2 ...] = tfile
redefine t1 [t2 ...] = tfile

Parameters

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.

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 tfile string is prefixed by a $ to define a foreign task (see the discussion below).

Description

The task 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 task 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 tfile), 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 foreign task 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 task 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 host_command_prefix 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 $N denotes argument N from the CL command line, with the first argument being number 1. The macro $0 is a special case, and is replaced the name of the task being executed. Likewise, $* 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.

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

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 task statements. A script file can only contain one script task.

Redefine has the same syntax as the task 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.

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.

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

2. Define a script task with associated parameter file (if the script is a procedure, 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.

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

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.

cl> task $run   = $run/nodebug
cl> task $debug = $run/debug
cl> task $top   = "$show proc/topcpu"

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 task 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