Mapping Procedure Parameters

Parameter mapping is the key component of a procedure's definition. Parameter mapping links the attributes or fields in your host application model with parameters in your procedure, which are then used by the procedure to select, update, insert, or delete host data.

The type of parameter you choose to map is dependent on the type of procedure you are creating. The Tables dialog box and Procedure Editor provide different options.

There are three types of parameters:

Parameters	Description
Filter parameter	Identify the records you want to select, update, or delete.
Output parameter	Contain data that is to be returned from the select procedure.
Data parameter	Fields or attributes to update or insert.

This Procedure	Requires...
Select	A filter parameter to identify the records to select and output parameters that return the requested data.
Update	A filter parameter to identify the records to update and data parameters that identify the attributes and/or fields to be updated.
Insert	Data parameters that identify the attributes and/or fields that are inserted.
Delete	A filter parameter to identify the records to delete.

Special Mapping Options

There are two circumstances where you may want to use special mapping options:

• To refine which records are returned
• The filter parameter you use to retrieve host data is not itself available as an attribute or recordset field that can be returned to a querying application.

To solve these situations:

Refine Which Records are Returned from a Recordset

Comparing parameters to recordset fields enables you to perform finely detailed filtering of data that a procedure retrieves from a recordset. This makes it possible to create complex procedure logic capable of sophisticated data manipulation. Only the records that satisfy all comparison mappings are retrieved.

These instructions assume that you have already inserted the recordset. If you have not done so, follow the instructions for inserting a recordset into a procedure.

To compare a filter parameter to a recordset field for a SELECT procedure:

1. Click the needed procedure in the Tables and procedures box in the Tables dialog box.
2. Click Procedure Editor to open the Procedure Editor.
3. Click the recordset containing the fields you want to compare to filter parameters.
4. Click the Recordset tab; on the Records tab, select Fetch/Update records as the Action to perform.

5. In the Records section, specify which matching records to retrieve from the recordset:

   • Select First matching record only to return the first record that matches the filter. If no matching records are found to satisfy the query, the procedure fails. If defined as First matching record only, the operation that leads away from the parent entity may reference fields in the recordset.
   • Select All matching records to return all the records that match the filter. Only the operation that leads away from the recordset may reference fields in the recordset.

6. In the Record filter section, click the Compare field to parameter column next to each recordset field that you want to use to filter the data that will be retrieved when this procedure runs; select a filter parameter from the list.

When the procedure runs, the parameter is compared to the data retrieved from the recordset; only the data matching all the compare filters is returned to the querying application.

Return Filter Parameters as Output Parameters

In some cases, a filter parameter you use to retrieve host data is not itself available as an attribute or recordset field that can be returned to a querying application. To solve this problem, you can map a filter parameter to an output parameter.

To map a filter parameter to an output parameter:

1. In the Tables dialog box, click the needed procedure in the Tables and procedures box.
2. Click the Advanced button beneath the list of output parameters to open the Parameter to Parameter Mapping dialog box. The output parameters for the current procedure are listed in the Output parameter column.
3. Click the Filter parameter column next to the output parameter you want to map. Then, click the list to select the filter parameter you want to map to the output parameter.
4. Repeat step 3 for each filter parameter you want to map to an output parameter.

More information

• Inserting entities into a procedure
• Procedures overview
• Creating procedures

Advanced Attribute Mapping

Use the Advanced Attribute Mapping dialog box to map an attribute or recordset field to multiple output parameters.

To map an attribute or recordset field to more than one output parameter:

1. In the Data Exchange tab, click Write attribute to parameter (for attributes) or Write field to parameter (for recordset fields) next to the attribute or recordset field you want to map to multiple output parameters.

2. Select Advanced from the list.

   The Advanced Attribute Mapping dialog box appears. The attribute or recordset field you are mapping appears in the Source attribute box. All the available output parameters appear in the Available items box. The list of available output parameters is derived from the output parameters you selected in the Tables dialog box. 3. Click each output parameter you want to map this attribute or recordset field to and click the right arrow. Do this for each output parameter.

   Each output parameter you map to this attribute or recordset field appears in the Destination items box.

3. To remove a output parameter from the mapping, click it in the Destination items box, click it and then click the left arrow.

4. Click OK.

   The Advanced Attribute Mapping dialog box closes. All the output parameters you mapped to this attribute or recordset field appear in the Write attribute to parameter box separated by commas.

Advanced Parameter to Parameter Mapping

In some cases, a filter parameter you use to retrieve host data is not itself available as an attribute or recordset field that can be returned to a querying application. To solve this problem, you can map a filter parameter to an output parameter in a SELECT procedure.

To map a filter parameter to an output parameter in a SELECT procedure:

1. In the Tables dialog box, click the procedure for which you want to map parameters in the Tables and procedures box.

2. Click the Advanced button beneath the list of output parameters to open the Parameter to Parameter Mapping dialog box. The Output parameter column lists the output parameters for the current procedure.

3. Click the Filter parameter column next to the output parameter you want to map. Then, click the list to select the filter parameter you want to map to the output parameter.

   The list of available filter parameters is derived from the Filter parameters box in the Tables dialog box. If the filter parameter you are mapping here is available in the form of an attribute or recordset field on an entity, we recommend that you map the attribute or recordset field to an output parameter instead of mapping the two parameters together.

4. Repeat step 3 for each filter parameter you want to map to an output parameter.

5. Click Close to return to the Tables dialog box.