<return> Step

Use the <return> step element to stop execution of the current block and optionally to return a returns value to the calling step. The <return> step element may appear only within the following elements:

• installSteps

• uninstallSteps

• control

• retarget

• then

• else

• block

• catch

• finally

• simpleSteps

• dependantCleanup

The presence of the returns=true attribute in an install, uninstall, or call block declaration mandates a corresponding uncaught <raise> or a <return> step in each execution path of the block definition.

The <return> step may appear anywhere in the block definition and generally follows the semantics for Java return statements. Depending on the complexity of the block, more than one <return> step may be required to ensure that all execution paths return a value. If additional steps are indicated subsequent to a return, a check-in error will be thrown, unless the <return> step appears in a <try> block and the additional steps are enclosed in the corresponding <finally> block. An execution path may also be terminated by a <raise> step, only if the <raise> step is not caught and handled in the current block scope. A <return> step may be used in a block even if the block does not specify a returns attribute, but in this case must not specify a value to return. If the <return> step specifies a value, but no returns attribute was specified for the block, a check-in error results.

Attributes for the <return> Step

The <return> step has one attribute value of type String. This value is the value to return. If no value is specified, the block stops execution without returning a value.

Example 2–4 Using the <return> Step in <try> and <finally> Blocks

The following example shows <return> steps in <try> and <finally> blocks. The value b will be returned (as in Java).

<try>
    <block>
        <return value="a"
    </block>
    <catch/>
    <finally>
         <return value="b">
    </finally>
</try>

Example 2–5 Using the <return>Step Conditionally

The following is an example of the <return> step used conditionally (line numbers were added for emphasis). If var1 is true, then the <return> step at line 5 would skip the remainder of the steps in the block. Lines 8 and 9 would not be executed at all. If var1 is not true, then the <return> step at line 9 would be the last step executed in the block.

1. <control name = "blah" returns="true">
2.   <varList>
3.   <var name="var1" default="val1"/>
4.   <var name="var2" default="val2"/>
5.   </varList>
6.   <if>
7.      <condition><istrue value=":[var1]"/></condition>
8.      <then>
9.         <return value=":[var2]">
10.     </then>
11.  </if>
12.  <assign varName="var2" value="new value"/>
13.  <return value=":[var2]"/>
14.</control>

Example 2–6 Using the <return> Step Conditionally Within a <try> Block

In contrast, the following example shows a conditionally used <return> step within a <try> block. Regardless of whether or not var1 is true, line 15 will always be the last line executed.

1. <control name="blah" returns="true">
2.   <varList>
3.   <var name="var1" default="val1"/>
4.   <var name="var2" default="val2"/>
5.   </varList>
6.   <try>
7.      <block>
8.          <if>
9.              <condition><istrue value=":[var1]"/></condition>
10.             <then>
11.                 <return value=":[var2]">
12.             </then>
13.         </if>
14.         <assign varName="var2" value="new value"/>
15.         <return value=":[var2]"/>
16.     </block>
17.  <catch/>
18.  <finally>
19.      <pause delaySecs="5"/>
20.  </finally>
21.   </try>
22.</control>

Example 2–7 Using the <return> Step Within an inlineSubplan

The following example shows a <return> step occurring within the <SimpleSteps> of an inlineSubplan or execSubplan body. Control is returned to the next step in the set of steps that call the inlineSubplan or execSubplan. The next step after the <return> step at line 4 is line 7.

1. <complexSteps>
2.   <inlineSubplan>
3.       <simpleSteps>
4.           <return/>
5.       </simpleSteps>
6.   </inlineSubplan>
7.   <inlineSubplan>
8.       <simpleSteps>
9.            <pause delaySecs="1"/>
10.      </simpleSteps>
11.  </inlineSubplan>
12.</complexSteps>