Cross-Reference Functions
This section describes the cross-reference XSLT extension functions in alphabetical order.
Syntax
xref:BulkPopulateDomainData(mapName, domainList, dataRowsPath, dataValuesPath, mode)
Description
The XREF bulk populate domain data function populates cross-reference data from XML. It sequences through the rows of data provided in the XML nodeset and uses the supplied domain list and data values path to access the values for each domain in each row. Each row of data is then inserted into the XREF framework for the specified map utilizing bulk insert to maximize performance. This function is expected to be used for processing large volumes of data. It provides an abstraction layer from the physical data persistence layer of the XREF framework. because inserts are done using bulk mode, duplicates are not looked for until the end of the insert sequence. If a duplicate is encountered, none of the rows of data will be inserted. When a domain contains multiple elements, each value for the domain must contain a compound value consisting of a value for each element in the domain separated by the concatenation string specified in the value map options. In this scenario, this function will unconcatenate the domain element values before inserting the data into the transformation framework.
Parameters
Parameter |
Description |
---|---|
mapName |
The name of a dynamic (cross reference) value map, as string. |
domainList |
A comma separated list of domain names identifying the order of the data values to be imported. |
dataRowsPath |
An XPath expression resulting in a series of XML nodes where each node represents one row of data. |
dataValuesPath |
An XPath expression (relative to each row of data) used to identify each node containing a data value within a row of data. The nodeset returned when this path is evaluated must contain the same number of nodes as there are domains in the specified domainList. |
mode |
Only ADD mode is supported. |
Returns
Boolean indicating success or failure of the process.
Syntax
xref:BulkPopulateElementData(mapName, elementList, dataRowsPath, dataValuesPath, mode)
Description
The XREF bulk populate element data function populates cross-reference data from XML. It sequences through the rows of data provided in the XML nodeset and uses the supplied pairs of elements and XPath expressions to access the values for the elements in each row. Each row of data is then inserted into the XREF framework for the specified map utilizing bulk insert to maximize performance. This function is expected to be used for processing large volumes of data. It provides an abstraction layer from the physical data persistence layer of the XREF framework. because inserts are done using bulk mode, duplicates are not looked for until the end of the insert sequence. If a duplicate is encountered, none of the rows of data will be inserted.
Parameters
Parameter |
Description |
---|---|
mapName |
The name of a dynamic (cross reference) value map, as string. |
elementList |
A comma separated list of element names identifying the order of the data values to be imported. |
dataRowsPath |
An XPath expression resulting in a series of XML nodes where each node represents one row of data. |
dataValuesPath |
An XPath expression (relative to each row of data) used to identify each node containing a data value within a row of data. The nodeset returned when this path is evaluated must contain the same number of nodes as there are domains in the specified domainList. |
mode |
Only ADD mode is supported. |
Returns
Boolean indicating success or failure of the process.
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 |
Example
This table lists examples of the modes with their descriptions and 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:
|
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:
|
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:
|
Syntax
xref:populateXRefRowNVP(mapName, referenceDomain, referenceNVP, targetDomain, targetNVP, mode)
Description
Use the xref:populateXrefRowNVP function to populate multiple elements in the cross-reference map with values.
Parameters
Parameter |
Description |
---|---|
mapName |
The name of the cross-reference map, as string. |
referenceDomain |
The name of the reference domain, as string. |
rreferencesNVP |
NVP list of reference elements and values, as string. |
targetDomain |
The name of the domain to be populated, as string. |
targetNVP |
NVP list of elements and values to be populated in the elements, 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 table lists the results for the populateXrefRowNVP 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 |
Example
This table lists the modes with their descriptions and exception reasons:
Mode |
Description |
Exception Reasons |
---|---|---|
ADD |
Adds the reference value and the value to be added. For example: xref:populateXRefRowNVP("Items", "PeopleSoft", "<Setid>SHARE</Setid> <ItemID>1005</ItemID>","Common", "<Common>” | generate-guid() | ”</Common>","ADD") adds the reference values SHARE/1005 in the PeopleSoft domain and the value <guid1> in the Common domain. |
Exceptions can occur for the following reasons:
|
LINK |
Adds the cross-reference value corresponding to the existing reference value. For example: xref:populateXRefRowNVP("Items", "PeopleSoft","<Setid>SHARE</Setid> <ItemID>1005</ItemID>","Retail", "<Product>RP0005</Product>","LINK") adds value RP005 to the Retail domain and links it to reference values SHARE/1005 in the PeopleSoft domain. |
Exceptions can occur due for following reasons:
|
UPDATE |
Updates the cross-reference value corresponding to an existing reference element-value pair. For example: xref:populateXRefRowNVP("Items", "PeopleSoft","<Setid>SHARE</Setid> <ItemID>1000</ItemID>","PeopleSoft", "<Setid>SHARE</Setid> <ItemID>10000</ItemID>","UPDATE") updates the value 1000 in the ItemID element of the PeopleSoft domain to value 10000. |
Exceptions can occur for the following reasons:
|
Syntax
xref:markForDelete(mapName, elementName, elementValue)
Description
Use the xref:markForDelete function to delete a value in a cross-reference map when the element specified is the only element for a single domain. The value in the element is marked as deleted. If multiple domains reference the element or the domain the element is referenced by has multiple primary elements, use the xref:markForDeleteNVP function instead.
A cross-reference map row should have at least two mappings. Therefore, if you have only two mappings in a row and you mark one value for delete, then the value in another element is also deleted.
Any element value marked for delete is treated as if the value does not exist. Therefore, you can populate the same element with the xref:populateXRefRow function in ADD mode. However, if the element value is marked for delete as a reference, it cannot be used in the LINK mode of xref:populateXRefRow function.
Parameters
Parameter |
Description |
---|---|
mapName |
The cross-reference map name, as string. |
elementName |
The name of the element from which you want to delete a value, as string. |
elementValue |
The value to be deleted, as string. |
Returns
This function returns true if deletion was successful; otherwise, it returns false.
An exception can occur for the following reasons:
The cross-reference map with the given name is not found.
The specified element name is not found.
The specified element name is not unique to a domain.
The specified value is empty.
The specified value is not found in the element.
Multiple values are found.
Example
The following code deletes the PS001 value in the PS element of the customers cross-reference map:
xref:markForDelete("customers","PS","PS001")
Syntax
xref:markForDeleteNVP(mapName, referenceDomain, referenceNVP)
Description
Use the xref:markForDeleteNVP function to delete a set of values in a cross-reference map for a specified domain. The values in the elements are marked as deleted.
A cross-reference map row should have at least two mappings. Therefore, if you have only two mappings in a row and you mark one value for delete, then the value in the other domain is also deleted.
Any values marked for delete are treated as if they do not exist. Therefore, you can populate the same elements with the xref:populateXRefRowNVP function in ADD mode. However, if the element value is marked for delete as a reference, it cannot be used in the LINK mode of xref:populateXRefRowNVP function.
Parameters
Parameter |
Description |
---|---|
mapName |
The cross-reference map name, as string. |
referenceDomain |
The name of the reference domain, as string. |
referenceNVP |
NVP list of reference elements and values that you want to delete, as string. |
Returns
This function returns true if deletion was successful; otherwise, it returns false.
An exception can occur for the following reasons:
The cross-reference map with the given name is not found.
The specified element name is not found.
All primary elements in this domain have not been specified.
The specified value is empty.
The specified value is not found in the element.
Multiple values are found.
Example
The following code deletes the specified values in the Setid and ItemID elements of the PeopleSoft domain from the Items cross-reference map:
xref:markForDeleteNVP ("Items","PeopleSoft","<Setid>SHARE</Setid><ItemID>1000</ItemID>")
Syntax
xref:lookupXRef (mapName, referenceElementName, xrefReferenceValue, elementName, needAnException)
Description
Use the lookupXRef function to look up a cross-reference element for a value that corresponds to a specific value in a reference element.
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 looked up for the value, as string. |
needAnException |
Specify true or false. If the needAnException parameter is set to true, an exception occurs if the value being looked up in the map is not found. If the needAnException parameter is set to false, an empty value is returned if the value being looked up in the map is not found. |
Returns
The value of the requested element.
An exception can occur for the following reasons:
The cross-reference map with the given name is not found.
The specified element names are not found.
The specified reference value is empty.
Multiple target values are found.
Example
The following code looks up the Common element of the customers cross-reference map for a value corresponding to the PS001 value in the PS element:
xref:lookupXRef("customers","PS","PS001","Common",true())
Syntax
xref:lookupXRefNVP (mapName, referenceDomain, referenceNVP, targetDomain, needAnException)
Description
Use the lookupXRefNVP function to look up cross-reference values that correspond to a specified set of values in a reference domain. All primary elements in the reference domain must be included in the reference NVP list, but any qualifier elements are optional.
Parameters
Parameter |
Description |
---|---|
mapName |
The name of the cross-reference map, as string. |
referenceDomain |
The name of the reference domain, as string. |
referenceNVP |
NVP list of reference elements and values, as string. |
targetDomain |
The name of the domain to be looked up for the values, as string. |
needAnException |
Specify true or false. If the needAnException parameter is set to true, an exception occurs if the value being looked up in the map is not found. If the needAnException parameter is set to false, an empty value is returned if the value being looked up in the map is not found. |
Returns
The return string includes values for all primary and qualifier elements in the target domain as an NVP list.
An exception can occur for the following reasons:
The cross-reference map with the given name is not found.
The specified domain names are not found.
The specified element names are not found.
The specified reference value is empty.
Multiple target values are found.
Example
The following code looks up the values of all elements in the Common domain of the Items cross-reference map that correspond to values SHARE/1000 in the PeopleSoft domain:
xref:lookupXRefNVP("Items","PeopleSoft","<Setid>SHARE</Setid><ItemID>1000</ItemID>","Common",true())