Variable Usage Rules This page last changed on Mar 17, 2008. .stickable, h1, h2, h3, h4, h5 false true Show Sticky notes Hide Sticky notes Save Cancel Oracle Data Service Integrator Documentation > Data Services Developer's Guide # Variable Usage Rules This section describes how variables may be used when customizing an update map expression. If you are new to update maps, it is recommended that you first read Understanding Update Maps. ### Variable Types and Scoping Rules Variables may be defined by a for-each block or by an update block (as an output variable). An output variable may be used in an expression if the expression is contained within an update block that depends on the update block that defines the variable. A for each block variable may be used by an expression if the expression is immediately inside the for-each block that defines the variable. However, if the defining for-each block contains any other for each blocks which also contain the expression, the variable may not be used in the expression. Example: an update map for a customer-orders data service
| The image to the left shows an update map for a logical data service about customers and orders (see Understanding Update Maps for more info). Notice that the update block for customers is selected and the name of its output variable `$CUSTOMER_key` is shown at the bottom of the screen (the output variable is also referred to as the key variable). In this case, `$CUSTOMER_key` can be referenced anywhere from within the update block for orders (e.g. in a mapping expression or in the condition for the update block). Also notice that we have two for-each blocks that define the variables `$customer` and `$order`. Within the update block for customers, only the `$customer` variable is visible and within the update block for orders only the `$order` variable is visible (with one exception which will be discussed next).
These restrictions are in place to prevent unintuitive or complicated behavior by the update map at runtime. If these rules are too restrictive for your application, you may want to consider using XQSE. However, there is one exception to the for each block variable usage rule. If the variable is used as part of a path expression that references a key value, then usage is valid as long as the expression is within the defining block. It is important to note that updates will be effectively disabled for such "outside" mappings (creates and deletes will still work). Example: an outside mapping to a key value
| In the image on the left, the `CUSTOMER_ID` element in the update block for orders is selected and its mapping expression (`fn-bea:value($customer/CID)`) is shown at the bottom of the screen. Normally, the variable `$customer` could not be used within the orders update block since it is not directly contained within the corresponding for-each block. However, since it is being used to reference `CID` it is allowed because `CID` is equivalent to the key value of the customer data service. Updates for this outside mapping will be disabled. That is, if `customer/CID` is modified in the input to the update map procedure, the CUSTOMER_ID element in the orders update block will not have the modified value.
### Updating Foreign Key Values The function `fn-bea:coalesce` takes 1 or more arguments and simply returns the first argument that is not empty. The function `fn-bea:coalesce-equal` works the same way except that it additionally checks that all non empty arguments are equal. If it finds that any two non empty arguments are not equal, it will throw an exception at runtime. The automatically generated update map may use `fn-bea:coalesce-equal` for the mapping expression for foreign key values if it can be inferred from the target data service that the values should always be equal. If an argument to `fn-bea:coalsece-equal` contains an a path expression that falls under the exception to the for each block variable rule mentioned above, then updates will be disabled for the entire expression containing `fn-bea:coalsece-equal`. If your automatically generated update map is in this situation and you wish to be able to update the foreign key value, you can simply remove the argument that contains the offending mapping. (See the example that follows) Example: coalesce-equal
| In the first image on the left, the `CUSTOMER_ID` element in the update block for orders is selected and its mapping expression (`fn-bea:coalesce-equal(...)`) is shown at the bottom of the screen. When the update map is used to create a customer with orders, the value for CID may not be known as it may be auto generated by an underlying relational database. This means that `$customer/CID` and `$order/OCID` may be empty. In this case the generated key value will be returned and the orders will get the value for CUSTOMER_ID via fn-bea:value($CUSTOMER_key/CUSTOMER_ID). If the update map is used to update or delete customers and orders, `$CUSTOMER_key/CUSTOMER_ID` will be empty but `$customer/CID` and `$order/OCID` should not be. This mapping contains an outside reference to the variable `$customer` so updates will be disabled for `customer/order/OCID` in the input to the update map procedure. To enable updates to `OCID`, we can remove the outside mapping. The second image on the left shows what the update map looks like after this modification.

Document generated by Confluence on Jan 13, 2009 15:57