This topic describes how to create custom IDL Tasks. The IDLTask function is the core of this capability. It provides one entry point for end users to create and execute an instance of the custom code.

See the following topics to learn more:

Benefits of Using 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.

Your First Custom IDL Task

This example shows how to create a custom task that returns the sum of two numbers:

  1. Create a scratch directory with write permissions to place the example files into, then add the scratch directory to the IDL Path.
  2. Copy the content below and save it to a file named addition.pro in the scratch directory:
    3.   pro addition, A=a, B=b, C=c
        compile_opt idl2
        c = a + b
      end
  3. Copy the JSON content below and save it in a file named addition.task in the scratch directory:
    4. {
      "name": "addition",
      "description": "Returns the sum of a and b.",
      "base_class": "IDLTaskFromProcedure",
      "routine": "addition",
      "schema": "idltask_1.1",
      "revision": "1.0.0",
      "parameters": [
        {
          "name": "A",
          "type": "INT",
          "direction": "input",
          "required": true,
          "test_exact": true
        },
        {
          "name": "B",
          "type": "INT",
          "direction": "input",
          "required": true,
          "test_exact": true
        },
        {
          "name": "C",
          "type": "INT",
          "direction": "output",
          "required": true
        }
      ]
    }
  4. Run the custom task using the IDLTask function at the IDL Console:
    5.   task = IDLTask('addition')
      task.A = 2
      task.B = 2
      task.Execute
      print, 'The sum is:', task.C
  5. The IDLTask stores the inputs. To update just one input and rerun, use:
    6.   task.B = 8
      task.Execute
      print, 'The sum is:', task.C
  6. If you look at the addition.task file, you will notice that for the input parameters of A and B, the test_exact key is set to true. Setting test_exact to true prevents non-integer floating point values as input. Run the following at the IDL Console and note that an error is generated:
  task = IDLTask('addition')
  task.A = 2.5

QUERY_IMAGE as a Custom IDL Task

This example shows how to wrap the QUERY_IMAGE routine into a custom task:

  1. Create a scratch directory with write permissions to place the example files into, then add the scratch directory to the IDL Path.
  2. IDL Task supports execution of a procedure with keywords. QUERY_IMAGE is a function with an argument. To support QUERY_IMAGE you build a thin procedure that wraps QUERY_IMAGE. Copy the content below and save it to a file named myqueryimage.pro in the scratch directory. 
    3.   pro myqueryimage, FILENAME=filename, $
        SUPPORTED=supported, $
        _REF_EXTRA=extra
         
        compile_opt idl2
         
        supported = Query_Image(filename, $
          _STRICT_EXTRA=extra)
           
      end
  3. Copy the JSON content below and save it in a file named myqueryimage.task in the scratch directory:
    4. {
      "name": "MyQueryImage",
      "description": "Returns information about an image format file.",
      "base_class": "IDLTaskFromProcedure",
      "routine": "myqueryimage",
      "schema": "idltask_1.1",
      "revision": "1.0.0",
      "parameters": [
        {
          "name": "FILENAME",
          "type": "STRING",
          "direction": "input",
          "required": true
        },
        {
          "name": "SUPPORTED",
          "type": "BOOLEAN",
          "direction": "output"
        },
        {
          "name": "CHANNELS",
          "type": "LONG",
          "direction": "output"
        },
        {
          "name": "DIMENSIONS",
          "type": "LONGARRAY",
          "dimensions": [2], 
          "direction": "output"
        },
        {
          "name": "PALETTE_EXISTS",
          "keyword": "HAS_PALETTE",
          "type": "BOOLEAN",
          "direction": "output"
        },
        {
          "name": "FORMAT",
          "keyword": "TYPE",
          "type": "STRING",
          "direction": "output"
        }
      ]
    }
  4. Review the parameter definition for DIMENSIONS below. QUERY_IMAGE returns an array containing 2 elements for the DIMENSIONS keyword. To expose that keyword for the task you define the parameter keys of type equal to LONGARRAY and dimensions of [2]. 
    5.     {
          "name": "DIMENSIONS",
          "type": "LONGARRAY",
          "dimensions": [2], 
          "direction": "output"
        }
  5. Review the parameter definition for FORMAT below. QUERY_IMAGE used TYPE as the keyword. For the task, we exposed the parameter name as FORMAT to help in clarification to users. IDL Task Parameter definition allows remapping of old keywords to new keywords by defining the parameter key of keyword and the parameter key of name. If the parameter definition did not have the keyword key, then it is implied that the name key is used as the keyword name when calling the routine. 
    6.     {
          "name": "FORMAT",
          "keyword": "TYPE",
          "type": "STRING",
          "direction": "output"
        }
  6. Run the custom task using the IDLTask function at the IDL Console:
    7.   task = IDLTask('myqueryimage')
      task.FILENAME = FILEPATH('rose.jpg', SUBDIR=['examples','data'])
      task.Execute
      print, 'The format is '+task.FORMAT+' with dimensions of:'
      print, task.DIMENSIONS
  7. Run the task against multiple files. Copy the content below and save it to a file named runmyqueryimagetask.pro in the scratch directory:
    8.   pro runMyQueryImageTask
        compile_opt idl2
         
        ; Define a data directory to search for data files
        dataDir = FilePath('', SUBDIR=['examples','data'])
        dataFiles = File_Search(dataDir,'*')
         
        ; Create an instance of MyQueryImage task
        task = IDLTask('MyQueryImage')
         
        ; Run MyQueryImage task against all files in the data directory
        ; to see which ones contain a PALETTE
        print,'Data files that contain palettes that '+$
          'can be read by QUERY_IMAGE:'
        foreach file, dataFiles do begin
          ; Update the FILENAME parameter on the task to the new file
          task.FILENAME = file
           
          ; Execute the task with each file
          task.Execute
           
          ; Check if supported and has a palette. 
          ; Print if the file has a palette
          if (task.SUPPORTED && task.PALETTE_EXISTS) then $
           print, task.FILENAME
        endforeach
         
        print,''
         
        ; Run MyQueryImage task against all files in data directory
        ; to see which ones are of JPEG format
        format = 'JPEG'
        print,'Data files that are of '+format+' format:'
        foreach file, dataFiles do begin
          ; Update the FILENAME parameter on the task to the new file
          task.FILENAME = file
           
          ; Execute the task with each file
          task.Execute
           
          ; Check if format looking for and print if it is
          if (task.FORMAT eq format) then $
           print, task.FILENAME
        endforeach
      end

See Also

Task Schema History