The functions described in this section are available only for writable datasets, that is, datasets for which the isWritable() function returns true. Invoking any of these functions on a non-writable dataset is a programming error and has unpredictable results.
Flushes any unsaved metadata changes to the backing file, closes the backing file, and turns the dataset into a read-only dataset. From now on, the isWritable() function returns false and further updates are impossible.
A writable dataset keeps its backing file open for updating after the dataset is created. Since the backing file is the current job (or a file in the job folder), it is necessary to close it before attempting to move or process job in any way. In practice it is seldom necessary to explicitly call the finishWriting() function because Switch automatically invokes it on the embedded dataset for a job at the following times:
When one of the Job.sendTo() or Job.fail() functions is invoked on the job.
When the entry point in which the dataset was created returns.
The set functions described below set the value of a leaf property. They succeed if:
The specified property exists and it is a leaf property: the property value is updated.
The specified property does not exist, but its immediate parent does exist and it is a struct: the property is created with the specified name and its value is set.
The specified property does not exist, but its immediate parent does exist and it is an array: the property is created with the specified index and its value is set; any missing array items (that is, siblings of the property with a lower index) are created as well and set to an empty string value.
Sets the value of the leaf property at the specified XMP location path to the specified string. Returns true if successful, false otherwise.
Same as setString but produces a decimal representation of the number; "precision" indicates the number of digits after the decimal point; if precision is zero the representation has no decimal point (that is, this is suitable for an integer number).
Same as setString but produces the string "True" or "False" depending the Boolean value.
Same as setString but produces a date-time representation in the ISO 8601 format. The class of the Date object is specific to the scripting environment in use.
To set the value of a child property, first verify that its parent exists, and if not, create the parent with the set functions described in the following section. It may be necessary to apply this process recursively to create the parent's parent.
To set the value of an item in an alt-text array, use the setLocalizedText() function described later. The above set functions do no allow a language selector in the specified XMP location path.
Modifies the value of a selected item in an alt-text array. Creates an appropriate array item if necessary, and handles special cases for the x-default item.
If the selected item is from a match with the specific language, the value of that item is modified. If the existing value of that item matches the existing value of the x-default item, the x-default item is also modified. If the array only has 1 existing item (which is not x-default), an x-default item is added with the given value.
If the selected item is from a match with the generic language and there are no other generic matches, the value of that item is modified. If the existing value of that item matches the existing value of the x-default item, the x-default item is also modified. If the array only has 1 existing item (which is not x-default), an x-default item is added with the given value.
If the selected item is from a partial match with the generic language and there are other partial matches, a new item is created for the specific language. The x-default item is not modified.
If the selected item is from the last 2 rules then a new item is created for the specific language. If the array only had an x-default item, the x-default item is also modified. If the array was empty, items are created for the specific language and x-default.
Returns true if successful, false if the specified property does not exist or is not an Alt-Text array.
The set functions described below create struct or array properties. They succeed if:
The specified property exists and it is has the appropriate type: nothing happens.
The specified property does not exist, but its immediate parent does exist and it is a struct: the property is created with the appropriate type.
The specified property does not exist, but its immediate parent does exist and it is an array: the property is created with the specified index and the appropriate type; any missing array items (that is, siblings of the property with a lower index) are created as well with the same type.
Creates a struct property at the specified XMP location path. Returns true if successful, false otherwise.
Creates an unordered array property ("Bag") at the specified XMP location path. Returns true if successful, false otherwise.
Creates an ordered array property ("Seq") at the specified XMP location path. Returns true if successful, false otherwise.
Creates an alternate array property ("Alt") at the specified XMP location path. Returns true if successful, false otherwise.
To change the type of a property between leaf, array and struct, first remove the property and then create it again with the appropriate set function.
Removes the property at the specified XMP location path and the complete sub-tree rooted at the property. If the property does not exist the function does nothing.