Item Pointer

ptr:MoveTo(ptrTarget[,strDataReference])

ptrTarget

pointer: A pointer to the target data item.  If strDataReference is not supplied, this pointer will be moved to point at the target data item.

strDataReference

string: Optional data reference.  If supplied, instead of moving this pointer to the target data item, the pointer will be moved to point at the item matching the supplied data reference, using the ptrTarget as a starting point.

None

N.B. If no item is found matching the supplied parameters, the pointer will be set to NULL.

The this pointer can be NULL when initially used (but not nil - it must be an item pointer).  It can also be used as its own first parameter - as long as it is pointing at a suitable object at the time (see example below).

The data reference can have percentage signs around it, but doesn't have to.  It can also begin with a '~' character, which references the this object, making it easier to create data references that are relative to a given object - see examples below.  Notice that you can use "~>" (or a data reference that begins "~>...") to move from a link to the record it links to.  Again, see examples below.  To learn more about data references, see Understanding Data References.  In general, there is a possible data item corresponding to every valid data reference (ignoring qualifiers).  However there can occasionally be exceptions.   One such exception is metafields.  Metafields have tag '_FIELD'.  This tag can have certain child tags (such as 'URL' and 'TEXT'), even though metafields do not have child items.  These metafield child tags are an advanced feature (they are not offered by the data reference assistant).  They provide additional options for presenting metafield data in queries and elsewhere.

The example below moves a pointer pi to point at various data items, using pi2 (and also pi itself in the last case) as the referenced target data item.  Note that it (for illustration purposes only) uses three slightly different ways of referencing the same data item, on 3 consecutive lines.

Where there is a need to create a new pointer, for example when filling a Result table, the fhGetItemPtr provides a quicker method as it creates a new pointer rather than moving a preexisting one.

pi = fhNewItemPtr()
pi2 = fhNewItemPtr()
pi2:MoveToFirstRecord("INDI")   -- Sets pi2 to point to first individual record.
pi:MoveTo(pi2)                  -- Moves pi to point to the record pointed to by pi2
pi:MoveTo(pi2,"~.NAME")         -- Moves pi to the first Name field for pi2
                             -- Next 3 different ways of doing the same thing...
pi:MoveTo(pi2,"~.BIRT.DATE")    -- moves pi to p2's birth date subfield
pi:MoveTo(pi2,"%~.BIRT.DATE%")  -- ditto (percentages allowed round data references)
pi:MoveTo(pi2,"INDI.BIRT.DATE") -- ditto (example with with no '~' character)
                             --
pi:MoveTo(pi2,"~.FAMC")         -- Moves to link to pi2's family record (as child)
pi:MoveTo(pi2,"~.FAMC>")        -- Moves to pi2's family record (as child)
pi:MoveTo(pi,"~.MARR.DATE")     -- Moves pi (from pointing at family record) to marriage date

pi:MoveTo(pi2,"~.FAMC")         -- Moves to link to pi2's family record (as child) 
pi:MoveTo(pi,"~>")         	-- Moves from link to the record linked to (i.e. the actual Family record)

pi:MoveTo(pi2,"~.FAMC")         -- Moves to link to pi2's family record (as child) 
pi:MoveTo(pi,"~>HUSB>")       	-- Moves pi from pointing at link to Family record, to pointing at the father's (i.e. HUSBand's) Individual record