Function Name	Position
Category	Set
Icon
Description	Return the index of the current item within its containing sequence
Inputs	Item Item to retrieve index of
Outputs	Index Index of the item within its sequence (zero-based)
Properties	None -

Usage

The Data Mapper Set Position function allows you to retrieve the index of an item within its sequence. As with many of the mapping functions, the Position component is often most useful in conjunction with other functions. To apply the Set Position function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using clubs_source.xsd:

<sport_clubs>
 <club>
  <name>New Town Football Club</name>
  <member>
   <active>Yes</active>
   <member_name>Chris Black</member_name>
   <member_since>2005</member_since>
   <won>League 2009</won>
   <won>Cup 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Jim Thomson</member_name>
   <member_since>2003</member_since>
   <won>League 2010</won>
  </member>
  <member>
   <active>No</active>
   <member_name>Barry Jones</member_name>
   <member_since>1996</member_since>
   <won>League 1999</won>
   <won>Cup 1999</won>
   <won>League 2000</won>
  </member>
 </club>
 <club>
  <name>City Netball Team</name>
  <member>
   <active>No</active>
   <member_name>Jacqueline Johnson</member_name>
   <member_since>1999</member_since>
   <won>National Championship 2001</won>
   <won>Regional Championship 2002</won>
   <won>National Championship 2002</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Joanne Smith</member_name>
   <member_since>2005</member_since>
   <won>Regional Championship 2007</won>
   <won>National championship 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Mary Owens</member_name>
   <member_since>2007</member_since>
   <won>National Championship 2008</won>
  </member>
 </club>
</sport_clubs>

For our target schema we will be using clubs_alt_target.xsd:

The data models sporting clubs and their members. Some of the elements can appear multiple times. Notice that the target XML has an item that is not present in the source: the "memb_num" attribute of the "player" element. Let's assume that this is a unique member number within each club. We will need to generate this number for each member while mapping the data. To assign the numbers in a sensible fashion, we will give integer values to each "member", starting at 1 and assigning the numbers in order of the member's join date, so that the oldest member has the smallest number and so on. Here is the Data Mapper with Source and Target imported:

Drag the Set Position function from the Component Palette into the mapping area:

The Position function takes one input 'Nodes', when this is set the output values are created, but before we do that let add a Sort function and connect it so it sorts the members on there joining date.

We can now connect the sorted members to the position 'Nodes' input. When this connection is made the Position function outputs are created, note that an additional index value is added to the members data.

Now we have access to the position of each "member" within its parent element, so we can use this to assign member numbers in join date order. However, the position uses a zero-based index, and we want our member numbers to start at 1 rather than zero. Let's add one to each position number to arrive at the member number in each case. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Choose an integer from the Data Type drop-down list and enter the number 1 as the Value.

Now drag an Add function from the Maths section onto the Mapper. Connect its first input to the Position function output and its second input to the Constant output.

Connect the output of the Add function to the "memb_num" input in the XML Writer. The members in each club will now have their own unique numbers starting at one.

Finally let's connect the remaining input and output connections. Remember to map "member_since" to "joined" - although we have used the item as a reference, we have not yet mapped it from Reader to Writer.

We can now execute the transform by pressing Shift-F5 or the Execute button (). The transform is applied and the file we selected as output opens in the editor:

<clubs>
 <team t_name="New Town Football Club">
  <player p_name="Barry Jones" is_active="No" memb_num="1">
   <joined>1996</joined>
   <title>League 1999</title>
   <title>Cup 1999</title>
   <title>League 2000</title>
  </player>
  <player p_name="Jim Thomson" is_active="Yes" memb_num="2">
   <joined>2003</joined>
   <title>League 2010</title>
  </player>
  <player p_name="Chris Black" is_active="Yes" memb_num="3">
   <joined>2005</joined>
   <title>Cup 2007</title>
   <title>League 2009</title>
  </player>
 </team>
 <team t_name="City Netball Team">
   <player p_name="Jacqueline Johnson" is_active="No" memb_num="1">
    <joined>1999</joined>
    <title>National Championship 2001</title>
    <title>Regional Championship 2002</title>
    <title>National Championship 2002</title>
   </player>
   <player p_name="Joanne Smith" is_active="Yes" memb_num="2">
    <joined>2005</joined>
    <title>Regional Championship 2007</title>
    <title>National championship 2007</title>
   </player>
   <player p_name="Mary Owens" is_active="Yes" memb_num="3">
    <joined>2007</joined>
    <title>National Championship 2008</title>
   </player>
  </team>
</clubs>

Each "player" has a "memb_num" attribute, with the number a member has reflecting their order of joining. The oldest players for each team have the number 1, with more recent players assigned ascending numbers.

Here we are using the Position value as a reference for assigning another value within the data. However, in many cases you may find the Position function useful as input to other functions, rather than just as a value in itself.