<capture> Element

The <capture> element defines the files and resources that are to be captured as part of this snapshot. The capture occurs only after the steps in the <prepare> block have executed. When the capture is complete, the steps in the <cleanup> block will execute.

The <capture> element children consist of one or more <addFile>, <addSnapshot>, and <addResource> elements. The files and directories that are listed in this block are captured in the order specified. The contained children can reference local parameters and variables that are declared by the snapshot block, as well as unhidden component substitution variables.

<addFile> Element

The <addFile> element is a child of the <capture> element and specifies a file that is to be captured as part of the containing snapshot.

ATTRIBUTES FOR THE <addFile> ELEMENT

The <addFile> element includes the following attributes:

• path – A required attribute that specifies the path name of a file or directory on the file system of the target host. This attribute can reference simple substitution variables.

• ownership – An optional attribute that specifies the ownership option for the captured file.

  One aspect of the installed state that is captured by the snapshot is file and directory ownership. This ownership is not the same as UNIX permissions. The ownership is more closely tied to the concept of reference counts. Specifically, a file or directory can be captured as being owned by one or more snapshots.

  If the file owner later changes as a result of another component installation, this change can be recognized and reported when the file is compared against its initial state. This feature helps to track down differences that result from one component unintentionally overwriting files associated with another component. Snapshot ownership information is captured in a repository on the target host, which is known as the owners table.

  The values of the ownership attribute have the following semantics:

  • SET_SELF – When the ownership is set in this way, the owners table is updated to contain a single entry for the associated file or directory. That entry lists the executing installed component and snapshot as owners. The entry also lists the capture area ID of the captured contents of the file or directory.

  • ADD_SELF – When the ownership is set in this way, the installed component and snapshot are added as additional owners and share the existing capture area ID as the previous owners.

  • ADD_TEMP – This value is like ADD_SELF except that a new capture is always created and its ID is always used for the new entry rather than sharing the ID of the other owners.

  If this attribute is omitted, the default value is SET_SELF.

• filter – An optional attribute of type boolean that describes whether to capture files, directories, or both.

  If the value of path is a directory, this attribute is used to indicate whether the directory itself, the files it contains, or both should be captured. If the value of path is not a directory, this attribute is ignored and the file is captured directly. If this attribute is omitted, the default BOTH is used.

  The values for this attribute are as follows:

  • DIRECTORIES

  • FILES

  • BOTH

• recursive – An optional attribute that indicates whether subdirectories should be recursively captured by using the current filter settings.

  If the value of path is a directory, this attribute indicates whether subdirectories should be recursively captured by using the current filter settings. If the value of path is not a directory, this attribute is ignored and the file is captured directly. The default value is true.

• displayName – An optional attribute that is a string to be included in the display when this snapshot entry is compared against another.

  This attribute can reference simple substitution variables.

<addSnapshot> Element

The <addSnapshot> element denotes that an external snapshot block should be executed and that its contents should be added to this snapshot.

Using an <addSnapshot> step is semantically equivalent to all of the following scenarios:

• Adding the <prepare> steps of the called snapshot to the end of the calling snapshot's prepare block

• Adding the <cleanup> steps of the called snapshot to the start of the calling snapshot's cleanup block

• Adding the <capture> steps of the called snapshot to the calling snapshot's capture block in place of the <addSnapshot> step

Make sure that the files that are referenced by the called and calling snapshot blocks do not conflict.

Any number of <addSnapshot> steps can appear within a <capture> element. The called snapshot itself can contain any number of <addSnapshot> steps within its <capture> element.

When files are added to a snapshot indirectly by using <addSnapshot> callouts, the topmost component that initiated the snapshot capture is considered to be the owner of the files, as opposed to the component that contained the <addFile> directive. Similarly, when a comparison is performed on a snapshot, only <diff> element <ignore> directives of the topmost component that initiated the snapshot are considered. The <diff> element <ignore> directives that are contained on components visited as a result of <addSnapshot> callouts are not considered.

The <addSnapshot> element has one required attribute of type entityName, blockName, which is the name of the external snapshot block to execute.

The <addSnapshot> element has the following child elements:

• <argList> – An optional element that is a list of arguments to pass to the snapshot block. This element can only appear one time.

• <Installed component targeter> – An optional element that identifies the component that contains the snapshot block. If this element is omitted, <thisComponent> is used.

<addResource> Element

The <addResource> element denotes a resource that is associated with the component that is to be captured as part of the containing snapshot. This element can only be included in simple components.

This element serves as a syntactic shorthand for an equivalent <addFile> element, as follows:

• If the associated resource is a directory resource with deployMode=ADD_TO, <addResource> is equivalent to the following statement:

  <addFile path="path-of-deployed-directory" filter="FILES" displayName="resourceSourcePath"/>

• If the associated resource is a directory resource with deployMode=REPLACE, <addResource> is equivalent to the following statement:

  <addFile path="path-of-deployed-directory" displayName="resourceSourcePath"/>

• Otherwise, the associated resource is a file-based resource, and <addResource> is equivalent to the following statement:

  <addFile path="path-of-deployed-file" displayName="resourceSourcePath"/>