xref:populateXRefRow

Syntax

xref:populateXRefRow(mapName, referenceElementName, referenceValue, elementName, elementValue, mode)

Description

Use the populateXRefRow function to populate a cross-reference element with a value.

Parameters

Parameter	Description
mapName	The name of the cross-reference map, as string.
referenceElementName	The name of the reference element, as string.
referenceValue	The value corresponding to the reference element name, as string.
elementName	The name of the element to be populated, as string.
elementValue	The value with which to populate the element, as string.
mode	The mode in which the function populates the element. You can specify any of the following values: ADD, LINK, or UPDATE. The mode parameter values are case-sensitive and must be specified in the uppercase only.

Returns

This function returns the cross-reference value being populated as a string.

This table lists the results for the Xref:populateXRefRow function.

Mode	Reference Value	Value to Be Added	Result
ADD	Absent Present Present	Absent Absent Present	Success Exception Exception
LINK	Absent Present Present	Absent Absent Present	Exception Success Exception
UPDATE	Absent Present Present	Absent Absent Present	Exception Exception Success

Mode

Reference Value

Value to Be Added

Result

ADD

Absent

Present

Absent

Present

Success

Exception

LINK

Absent

Present

Absent

Present

Exception

Success

Exception

UPDATE

Absent

Present

Absent

Present

Exception

Success

Example

This table lists examples of the modes with their descriptions and exception reasons:

Mode Description Exception Reasons

Mode	Description	Exception Reasons
ADD	Adds the reference value and the value. For example: `xref:populateXRefRow("customers", "PS","PS101","Common","CM001","ADD")` adds the reference value PS101 in the PS element and the value CM001 in the Common element of the customers cross-reference map.	Exceptions can occur for the following reasons: The specified cross-reference map is not found. The specified elements are not found. The values provided are empty. The value being added is not unique across that element for that map. The element for that row already contains a value. The reference value exists.
LINK	Adds the cross-reference value corresponding to the existing reference value. For example: `xref:populateXRefRow("customers", "Common","CM001","SBL","SB-101", "LINK")` adds the value SB-101 in the SBL element of the customers cross-reference map and links it to the value CM001 in the Common element.	Exceptions can occur for the following reasons: The specified cross-reference map is not found. The specified elements are not found. The values provided are empty. The reference value is not found. The value being linked exists in that element for that map.
UPDATE	Updates the cross-reference value corresponding to an existing reference element-value pair. For example: `xref:populateXRefRow("customers","PS", "PS100","PS","PS1001","UPDATE")` updates the value PS100 in the PS element of the customers cross-reference map to value PS1001.	Exceptions can occur for the following reasons: The specified cross-reference map is not found. The specified elements are not found. The values provided are empty. The value being updated is not unique across that element for that map. Multiple values are found for the element being updated. The reference value is not found. The element for that row does not have a value.

ADD

Adds the reference value and the value. For example:

xref:populateXRefRow("customers", 
"PS","PS101","Common","CM001","ADD")

adds the reference value PS101 in the PS element and the value CM001 in the Common element of the customers cross-reference map.

Exceptions can occur for the following reasons:

The specified cross-reference map is not found.
The specified elements are not found.
The values provided are empty.
The value being added is not unique across that element for that map.
The element for that row already contains a value.
The reference value exists.

LINK

Adds the cross-reference value corresponding to the existing reference value. For example:

xref:populateXRefRow("customers", 
"Common","CM001","SBL","SB-101", 
"LINK")

adds the value SB-101 in the SBL element of the customers cross-reference map and links it to the value CM001 in the Common element.

Exceptions can occur for the following reasons:

The specified cross-reference map is not found.
The specified elements are not found.
The values provided are empty.
The reference value is not found.
The value being linked exists in that element for that map.

UPDATE

Updates the cross-reference value corresponding to an existing reference element-value pair. For example:

xref:populateXRefRow("customers","PS", 
"PS100","PS","PS1001","UPDATE")

updates the value PS100 in the PS element of the customers cross-reference map to value PS1001.

Exceptions can occur for the following reasons:

The specified cross-reference map is not found.
The specified elements are not found.
The values provided are empty.
The value being updated is not unique across that element for that map.
Multiple values are found for the element being updated.
The reference value is not found.
The element for that row does not have a value.