IDLTask

IDL Tasks are an object-oriented API to encapsulate IDL procedures.

IDL Tasks provide the following to users:

• One entry point for users through IDLTask function.
• Stores all input and output in the IDLTask object for easy access.
• Discover available tasks through QueryTaskCatalog Task.
• Provides introspection to learn about the input parameters and their requirements.
• Provides validation of input for expected data types, available choices, ranges, and any additional constraints a task has defined.

IDL Tasks provide the following to developers:

• Create new procedures and allow IDLTask to validate inputs instead of having to write additional code in the routine.
• Allows wrapping existing libraries as IDL Tasks by creating a task file (*.task) that maps to library routines.
• Provides information on each parameter on direction, expected data types, available choices, ranges, and more.

• IDL Tasks can be executed from other programming languages; see IDL Task Engine for details.

  If you have an application using the IDL Task Engine and want task information, use QueryTask Task and QueryAllTasks Task.

See Custom Tasks for details on creating tasks.

Syntax

Result = IDLTask( TaskName, [, ERROR=error])

or

Result = IDLTask( TaskFileName, [, ERROR=error])

or

Result = IDLTask( TaskTemplateHash, [, ERROR=error])

Arguments

TaskName

Specify a string with the name of the task to build. This argument must match a .task file on the !Path or in the current directory. The current directory is searched first, then !Path is used. If more than one task file with the given name is found in !Path, the first task file found will be used. The following are valid strings to use:

• QueryAllTasks
• QueryTaskCatalog
• QueryTask

or

TaskFileName

Specify the file to a task template to load.

or

TaskTemplateHash

Specify a hash containing the task definition.

Return Value

The IDLTask function returns a reference to an IDLTask object. Use the returned reference to set parameters and execute the task by changing properties or calling methods.

Keywords

ERROR

Set this keyword to a named variable that will contain any error message issued during execution. If no error occurs, the ERROR variable will be set to an empty string ('').

When this keyword is not set and an error occurs, the function returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine.

Methods

• AddParameter
• Dehydrate
• Execute
• Parameter
• ParameterNames
• RemoveParameter

Properties

ABORTED

A Boolean that returns true if the task was aborted during Execute. Not all tasks support aborting; in these cases the property always returns false.

DESCRIPTION

Text describing the task. In the task template this is defined with the "description" key.

DISPLAY_NAME

The name of the task as it appears in the user interface. In the task template this is defined with the "display_name" key.

NAME

The name of the task. In the task template this is defined with the "name" key.

REVISION

A string with the semantic revision number of the task. The "revision" key is for development purposes only. The revision number does not affect which task file is loaded.

TAGS

A scalar string or an array of strings that help categorize the task. It can be empty with a value of !NULL. In the task template this is defined with the "tags" key.

IDLTask::AddParameter

The IDLTask::AddParameter procedure method allows the addition of a parameter after IDLTask creation. The same parameter instance can be added to multiple tasks, allowing any updates to the parameter's VALUE to be shared by all tasks.

Syntax

task.AddParameter, Parameter [, ERROR=error]

Arguments

Parameter

Specify an object inheriting from IDLParameter to add to the task. If the NAME property of this parameter matches that of an existing parameter owned by the task, then it will replace the original parameter with this reference.

Keywords

ERROR

Set this keyword to a named variable that will contain any error message issued during execution. If no error occurs, the ERROR variable will be set to an empty string ('').

When this keyword is not set and an error occurs, the function returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine.

IDLTask::Dehydrate

The IDLTask::Dehydrate function method returns a hash that details each property of the task. It also includes a list that contains the hash returned by calling Dehydrate on each of the IDLParameter objects owned by this task.

Syntax

Result = task.Dehydrate( [ERROR=error])

Return Value

A hash comprised of IDL primitive values that describes this task and all of its parameters.

Arguments

None

Keywords

ERROR

Set this keyword to a named variable that will contain any error message issued during execution. If no error occurs, the ERROR variable will be set to an empty string ('').

When this keyword is not set and an error occurs, the function returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine.

IDLTask::Execute

The IDLTask::Execute method runs the task synchronously.

Syntax

task.Execute, [ERROR=error] [, Task Keywords]

Arguments

None.

Keywords

Task Keywords

Any parameter can be referenced as a keyword by using the parameter NAME when calling Execute method. If set as a keyword, the value will override the current value for input parameters. The keyword for output parameters must be set to a named variable to retrieve the result, or you can access them on the IDLTask object using the "." dot notation.

ERROR

Set this keyword to a named variable that will contain any error message issued during execution. If no error occurs, the ERROR variable will be set to an empty string ('').

When this keyword is not set and an error occurs, the function returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine.

IDLTask::Parameter

The IDLTask::Parameter function method returns a reference to the IDLParameter object with the requested name. You can then query the parameter to learn more about it, including the rules (constraints) for setting values to it.

Syntax

Result = task.Parameter(TaskProperty [, ERROR=error])

Return Value

A reference to an IDLParameter object owned by this task whose NAME property matches the TaskProperty argument.

Arguments

TaskProperty

Specify a string with the property name for the given IDLTask. Use the following code to print a list of parameter names for a task:

task = IDLTask('TaskName')

names = task.ParameterNames()

print, names

Keywords

ERROR

Set this keyword to a named variable that will contain any error message issued during execution. If no error occurs, the ERROR variable will be set to an empty string ('').

When this keyword is not set and an error occurs, the function returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine.

IDLTask::ParameterNames

The IDLTask::ParameterNames function method returns a list of parameter names for a given task. The order of the parameter names will match the order in which they were defined in the task template.

Syntax

Result = task.ParameterNames( [ERROR=error])

Return Value

A string array containing the names of all the IDLParameters owned by this task. Parameters that have their HIDDEN property set to true will not be included in this array.

Arguments

None.

Keywords

ERROR

Set this keyword to a named variable that will contain any error message issued during execution. If no error occurs, the ERROR variable will be set to an empty string ('').

When this keyword is not set and an error occurs, the function returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine.

IDLTask::RemoveParameter

The IDLTask::RemoveParameter procedure method allows the removal of a parameter after IDLTask creation.

Syntax

task.RemoveParameter, ParameterName [, ALL=all] [, ERROR=error]

Arguments

ParameterName

Specify a string matching the NAME property of the IDLParameter to remove from the task. An array of names can be used to remove multiple IDLParameters at once.

Keywords

ALL

Set this keyword to remove all IDLParameters from the task, instead of only the IDLParameter matching the ParameterName argument.

ERROR

Set this keyword to a named variable that will contain any error message issued during execution. If no error occurs, the ERROR variable will be set to an empty string ('').

When this keyword is not set and an error occurs, the function returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine.

Version History

8.5.2	Introduced
8.7	Added the REVISION property
8.7.1	Added the TAGS property