BuildDataRef builds a full data reference with instance indices from an item pointer, and provides the record idEvery record in Family Historian has a numeric Record ID, which uniquely identifies it within its type of record. and type tag for the associated record. If the pointer is invalid it returns empty strings and 0 record id. This functionA ‘function’ is an expression which returns values based on computations. Typically, functions require data to be supplied to them as ‘parameters’. A function in Family Historian is similar to a ‘function’ as used in spreadsheet applications (such as MS is a compatible evolution of the previous BuildDR function.

GetDataRefPtr reverses the process and supplies an item pointer for a data reference, record id, and record type tag. The data reference may be relative to the record root tag, e.g. “~.NAME”, providing the record type tag is supplied. If the record type tag is omitted, it is extracted from the full data reference. If any parameters are invalid it returns a NULL pointer.

Requires: None

Code

--[[
@function:	BuildDataRef
@description:	Get Full Data Reference for Pointer
@parameters:	Item Pointer
@returns:	Data Reference String, Record Id Integer, Record Type Tag String
@requires:	None
]]

function BuildDataRef(ptrRef)

	local strDataRef = ""		-- Data Reference with instance indices e.g. INDI.RESI[2].ADDR
	local intRecId   = 0		-- Record Id for associated Record
	local strRecTag  = ""		-- Record Tag of associated Record type i.e. INDI, FAM, NOTE, SOUR, etc

	-- getDataRef() is called recursively per level of the Data Ref
	-- ptrRef points to the upper Data Ref levels yet to be analysed
	-- strRef compiles the lower Data Ref levels including instances

	local function getDataRef(ptrRef,strRef)
		local ptrTag = ptrRef:Clone()
		local strTag = fhGetTag(ptrTag)			-- Current level Tag
		ptrTag:MoveToParentItem(ptrTag)
		if ptrTag:IsNotNull() then			-- Parent level exists
			local intSib = 1
			local ptrSib = ptrRef:Clone()		-- Pointer to siblings with same Tag
			ptrSib:MovePrev("SAME_TAG")
			while ptrSib:IsNotNull() do		-- Count previous siblings with same Tag
				intSib = intSib + 1
				ptrSib:MovePrev("SAME_TAG")
			end
			if intSib > 1 then 	strTag = strTag.."["..intSib.."]" end
			getDataRef(ptrTag,"."..strTag..strRef)	-- Now analyse the parent level
		else
			strDataRef = strTag..strRef		-- Record level reached, so set return values
			intRecId   = fhGetRecordId(ptrRef)
			strRecTag  = strTag
			if not fhIsValidDataRef(strDataRef) then print(strDataRef.." is Invalid") end
		end
	end -- local function getDataRef

	if type(ptrRef) == "userdata" then getDataRef(ptrRef,"") end

	return strDataRef, intRecId, strRecTag

end -- function BuildDataRef

--[[
@function:	GetDataRefPtr
@description:	Get Pointer for Full Data Reference
@parameters:	Data Reference String, Record Id Integer, Record Type Tag String (optional)
@returns:	Item Pointer which IsNull() if any parameters are invalid
@requires:	None
]]

function GetDataRefPtr(strDataRef,intRecId,strRecTag)
	strDataRef = strDataRef or ""
	if not strRecTag then
		strRecTag = strDataRef:gsub("^(%u+).*$","%1")	-- Extract Record Tag from Data Ref
	end
	local ptrRef = fhNewItemPtr()
	ptrRef:MoveToRecordById(strRecTag,intRecId or 0)	-- Lookup the Record by Id
	ptrRef:MoveTo(ptrRef,strDataRef)			-- Move to the Data Ref
	return ptrRef
end -- function GetDataRefPtr

 

Usage

local ptrRef = fhNewItemPtr()
ptrRef:MoveToFirstRecord("FAM")
ptrRef:MoveToFirstChildItem(ptrRef)
print( BuildDataRef(ptrRef) )		-->>	FAM.MARR	1	FAM

ptrRef = GetDataRefPtr("~.NAME",2,"INDI")
print(fhGetDisplayText(ptrRef))		-->>	Name: Julia Amanda FISH

ptrRef = GetDataRefPtr("INDI.NAME",2)
print(fhGetDisplayText(ptrRef))		-->>	Name: Julia Amanda FISH

ptrRef:MoveToFirstRecord("INDI")
while ptrRef:IsNotNull() do
	local strRef, intId, strTag = BuildDataRef(ptrRef)
	print(strRef, intId, strTag)	-->>	INDI.NAME	1	INDI
	ptrRef = GetDataRefPtr(strRef,intId)
	print(fhGetDisplayText(ptrRef))	-->>	Name: Anthony Edward MUNRO
	ptrRef:MoveNextSpecial()
	if intId > 1000 then break end
end

 

Previous Code

--[[
@function: BuildDR
@description: Get Data Reference for Tag
@parameters: Item Pointer
@returns: Data reference String (excluding index)
@requires: none
]] 
function BuildDR(ptr)
   local ptrTemp = fhNewItemPtr()
   ptrTemp:MoveTo(ptr)
   strDR = fhGetTag(ptrTemp)
   while fhHasParentItem(ptrTemp) do
      ptrTemp:MoveToParentItem(ptrTemp)
      strDR = fhGetTag(ptrTemp)..'.'..strDR
   end
   return strDR
end