diff options
Diffstat (limited to 'pkg/language/doc/task.hlp')
| -rw-r--r-- | pkg/language/doc/task.hlp | 161 |
1 files changed, 161 insertions, 0 deletions
diff --git a/pkg/language/doc/task.hlp b/pkg/language/doc/task.hlp new file mode 100644 index 00000000..d5e4aacc --- /dev/null +++ b/pkg/language/doc/task.hlp @@ -0,0 +1,161 @@ +.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 |