Each ENVITask is defined by a set of parameters. Each has constraints on data type, values, etc. The ENVIParameterENVIVirtualizableURIArray object is used when an ENVITask has a parameter defined as an array of type ENVIVirtualizableURI.
Syntax
Result = ENVIParameterENVIVirtualizableURIArray( [, Properties=value])
Properties
Properties can be set as keywords to the function during creation, or retrieved using the "." notation after creation. The NAME property is required on initialization. The VALUE property is the only property that can be updated after creation.
AUTO_EXTENSION, CHOICE_LIST, DEFAULT, DESCRIPTION, DIMENSIONS, DIRECTION, DISPLAY_NAME, FOLD_CASE, IS_DIRECTORY, IS_TEMPORARY, NAME, REQUIRED, TYPE, VALUE
Methods
Dehydrate
Hydrate
Validate
Return Value
The result is a reference to a newly created object.
Properties
Three properties control if and when this parameter will automatically generate a value when the parent task runs: AUTO_EXTENSION, IS_DIRECTORY, and IS_TEMPORARY. The primary factor is whether this parameter represents a file URI or a directory URI, as indicated by the IS_DIRECTORY property.
If this parameter represents a directory URI, then whenever VALUE = !NULL, this parameter will generate a temporary folder name in the ENVI Output Directory preference location. The folder will be named [task name]_[parameter name][Date][Random].
If this parameter represents a file URI, then two other properties apply. The AUTO_EXTENSION property defines the file extension that will be used. If AUTO_EXTENSION = !NULL, then no filename will be generated. The IS_TEMPORARY property defines whether the generated file(s) will be deleted when ENVI closes. Other factors dictate when temporary filenames will be generated:
- DIRECTION = "INPUT"
- VALUE = !NULL
- AUTO_EXTENSION != !NULL
- This parameter is referenced by a sibling parameter in the same task as its URI_PARAM property
- That sibling has DIRECTION = "OUTPUT"
- That sibling has REQUIRED = True
The file will be named [task name]_[parameter name][Date][Random].[AUTO_EXTENSION], and will be created in the ENVI Output Directory preference location.
AUTO_EXTENSION
A scalar string to use as the file extension when the ENVITask framework automatically generates a VALUE for this parameter. In the task template this is defined with the auto_extension key.
Note that an empty string value for this property is valid and will result in a filename without an extension. Only !NULL will prevent the automatic generation of a filename.
If DIMENSIONS contains any asterisks (*), then that dimension will be substituted with a 1 when allocating the string array for the generated filenames.
CHOICE_LIST
A 1D array that lists the possible values for the parameter. The default is !NULL. The values of this property must adhere to the TYPE property. In the task template this is defined with the choice_list key.
DEFAULT
The value returned by the VALUE property if the user does not explicitly set VALUE. The default is !NULL. The values of this property must adhere to the TYPE property. In the task template this is defined with the default key.
DESCRIPTION
A string describing the purpose of the parameter with respect to the task. In the task template this is defined with the description key.
DIMENSIONS
The dimensions of the array, which is required on initialization. The dimensions can be specified with an array of integers or a scalar string. If the number of elements in any dimension does not matter, then use a string value of an asterisk (*) for that dimension. In the task template this is defined with the required dimensions key.
- 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 three rows: [*, 3]
DIRECTION
A string that indicates whether the parameter acts as "INPUT" or "OUTPUT". The default is "INPUT". In the task template this is defined with the direction key.
DISPLAY_NAME
A string for the display name of the parameter that could be used to build a user interface. It can contain spaces and special characters. In the task template this is defined with the display_name key. If not set, the value will default to the NAME property's value.
IS_DIRECTORY
A boolean value that indicates if the VALUE of an ENVIURI parameter should be treated as a directory or a URI to a file. When the parent ENVITask is executed and the VALUE property is set to !NULL and the is_directory key is set to true, then a subdirectory will be created under the ENVI Output Directory preference location. The base name will be [taskname]_[parameter name], and the parameter's VALUE will be set to that new directory. In the task template this is defined with the is_directory key.
IS_TEMPORARY
A boolean value that indicates if filenames automatically generated by the ENVITask framework will be deleted when ENVI closes. Ancillary files for output objects will also be deleted, such as .hdr files for ENVIRasters. In the task template this is defined with the is_temporary key.
FOLD_CASE
A boolean value that indicates whether the parameter’s VALUE must match the case provided when CHOICE_LIST is set. The default value is 0, which makes the CHOICE_LIST case-sensitive. For example, if the CHOICE_LIST is set to ["Abc","abc"] then a VALUE set to “ABC” will fail. Set FOLD_CASE to 1, to bypass this behavior. In the task template this is defined with the fold_case key.
NAME
The name of the parameter which is required on initialization. The parameter’s value can be set and retrieved from the ENVITask with the "." dot notation using this name. The name can also be used in the ENVITask::Parameter method to retrieve the parameter object. NAME must be a valid IDL variable name. In the task template this is defined with the name key. Use DISPLAY_NAME for a better user interface label.
REQUIRED
A boolean value that indicates whether the parameter is required or not. The default is 0, which allows the parameter to be optional. In the task template this is defined with the required key.
TYPE
When the type key is defined as ENVIVirtualizableURIArray in the task template, the ENVIParameterENVIVirtualizableURIArray object is created and populated with the key/value pairs defined in the template. The returned TYPE property is ENVIVirtualizableURIArray.
VALUE
The current value of the parameter. The parameter's VALUE can be set at any time through ENVITask using "." dot notation using the NAME of the parameter, or directly on the parameter object. The value of this property must adhere to the TYPE property. Setting this property will internally invoke the Validate() method, and will throw an error if the new value is invalid. If you set VALUE to a one-element array, it will be converted to a scalar during validation.
Setting VALUE to * will create an object that is virtual. Otherwise, it will be written to disk.
Version History
API Version
4.2
See Also
ENVITask, ENVITask::Parameter, ENVIParameterENVIVirtualizableURI