retarget Step Execution Semantics

When a <retarget> step is encountered, we first evaluate the "host" attribute in the context of the current host of the caller.

If the value of the "host" attribute is different from the name of the current host, then the following steps are taken:

1. We resolve the host name to an actual host. If no such host exists, an error is raised.

2. We verify that the current user has "plan run" permission on the the given host. If not, an error is raised.

3. We verify that the root physical host of the host contains an RA, can be connected to, and is updated and prepared. If not, an error is raised.

4. We obtain a lock on the host, while retaining locks on all previously visited hosts. If the current execution thread already locks the host, this operation is effectively a no-op. If the host is already locked by another execution thread, this operation will block until the host is unlocked. If the request for a lock would result it a deadlock, then an error is raised.

5. The host becomes the new "current" host. The "physical" host is reset based on the new "current" host. The "initial" host does not change.

Once the above has completed, variables of the <varList> element are evaluated in the context of the new current host. Local variables may hide variables of enclosing scopes. Then each of the steps is executed in the context of the new current host.

Finally, if the retarget operation changed the current host, then it is unlocked as appropriate and the current host is reset to the current host of the caller. Note that if the host was locked previously in the current execution thread, then it remains locked until the block that first acquired the lock completes.

An empty <retarget> block is still useful as a mechanism to prevalidate that the current user has appropriate permissions, and that the host is properly prepared.