Task Template for IDL 8.7.1

This topic describes the fields (also called keys) in a task template for use with IDL 8.7.1 or later.

Task Keys

This table describes the keys that provide an overview of the task. Refer to IDLTask for additional details.

Key

Required

Description

name

Yes, if storing the task definition to disk

A string with the name of the task. This name is used when calling the IDLTask function to create an instance of the task. The name of the task file must match the value of this key and must be a valid IDL variable name.

base_class

Yes

A string with the name of the class to use; the most common is IDLTaskFromProcedure.

schema

Yes

A string containing the schema of the task definition. The schema is: idltask_1.1 . IDL will support this schema in future releases if a new schema is introduced.

routine

Yes, when used with IDLTaskFromProcedure

The routine that is called when Task.Execute is invoked.

display_name

No

A string with the name of the task for display purposes. Spaces and special characters are allowed.

description

No

A scalar string or an array of strings that help categorize the task. It can be empty with a value of !NULL.

revision

No

A string with the semantic revision number of the task. Semantic versioning provides a quick way to extract information about a new task release using a convention of X.Y.Z, where:

  • X represents the major version. An incremented value indicates that task additions and updates are not backward-compatible.
  • Y represents the minor version. An incremented value indicates that task additions and updates are backward-compatible.
  • Z represents the patch number. An incremented value indicates bug fixes that do not affect the task.

The revision key is for development purposes only. The revision number does not affect which task file is loaded. Whichever task file is found first will be used. If revision is not set, it will default to a value of 1.0.0.

tags

No

A scalar string or an array of strings that helps categorize the task.

parameters

No

A LIST of HASHs of key/value pairs, described in the Parameter Keys table below.

Parameter Keys

This table describes the keys that belong to the parameters group in a task definition; these are repeated for each parameter. Depending on the parameter type, there can be additional keys. Refer to the IDLParameter* topics to find out specific information about a given parameter. The mapping of the parameter properties to the task definition is 1:1, if the parameter property name is TEST_EXACT then the task definition key is test_exact.

Key

Required

Description

 
name

Yes

The name of the parameter as it appears to the end user. This key must be a valid IDL variable name.

 
type

Yes

A scalar string indicating the parameter type to use on creating an instance of the task.

Basic scalar data type string values are:

BYTE, INT, UINT, LONG, ULONG, LONG64,ULONG64, FLOAT, DOUBLE, COMPLEX, DCOMPLEX, STRING, BOOLEAN, LIST, HASH, DICTIONARY, ORDEREDHASH

Basic array data types must include the dimensions key and type string values are:

BYTEARRAY, INTARRAY, UINTARRAY, LONGARRAY, ULONGARRAY, LONG64ARRAY,ULONG64ARRAY, FLOATARRAY, DOUBLEARRAY, COMPLEXARRAY, DCOMPLEXARRAY, STRINGARRAY, BOOLEANARRAY

The type key value can be set to a class name to indicate that the user must provide an object of the given class name. 

dimensions

No for scalar, Yes for array

A scalar string specifying the required dimensions for a parameter, if type specified is an *ARRAY type.

If the number of elements in any dimension does not matter, then use an asterisk ('*') for that dimension.

  • Example of a three-element array declaration: "[3]"
  • Example of a 1D array with any number of elements: "[*]"
  • Example of a 2D array with any number of columns or rows: "[*, *]"
  • Example of a 2D array with a specific number of elements: "[3, 256]"
  • Example of a 2D array with any number of columns and 3 rows: "[*, 3]"
 
keyword

No

 The internal keyword that the parameter should map to when invoking the routine. If it is the same as the name key, then you do not need to create this key. 
display_name

No

A string with the name of the parameter for display purposes. Spaces and special characters are allowed. 

description

No

 A string with a description of the parameter. 
direction

No

Specify if the parameter is input or output. If this key is not set, then direction defaults to input.

 

required

No

A boolean value that indicates whether the parameter is required or not. The default is false, which allows the parameter to be optional. 

default

No

The default value of the parameter if the end user does not provide a value. 

hidden

No

A boolean value that indicates whether the parameter is visible to the user or not. The default is false, which means the user can see it and set its value. Set this key to true to prevent the user from seeing the parameter or changing its value. You must also set the default key to the desired value.

 
additional keys

No

Depending on the parameter there may be additional keys available to define. For example for a type set to STRING, there is fold_case and choice_list. You could use the QueryProperty static method on the given parameter class to discover the available keys:

IDL>print, IDLParameterString.QueryProperty()

Revision History

This section summarizes the updates to task templates, compared to the previous release:

See Also

Task Schema History, Custom IDL Tasks