View source for Programmer Guide/Command Reference/IREF

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
The <code>IREF</code> command returns the [[Programmer Guide/Concepts/IREF|internal reference]] (<code>IREF</code>) of the currently selected element of the supplied XML [[Programmer_Guide/Shell_Items/File|file item]], or, if you provide additional element data, the internal reference for the respective element of the supplied XML file item. If this information is not available, or not applicable, the <code>IREF</code> command will return the empty string.

== Iref of the currently selected element ==
The basic form of the <code>IREF</code> command retrieves the iref of the currently selected element:
 <var>var</var> := IREF <var>xmlfile</var> /Format [ /Attribute=<var>irefAttr</var> ] [ /Baseposition=<var>basePos</var> ] [ [[Programmer_Guide/Command_Reference_Options/Silent|/Ilent]] ]
Note that the <code>/Format</code> option is mandatory.

== Iref of a {{STX}} file position ==
; When you supply an {{STX}} [[Programmer Guide/Concepts/File_position|file position]], <var>position</var>, the <code>IREF</code> command retrieves the iref of the element whose position you supplied:
 <var>var</var> := IREF <var>xmlfile</var> /Format <var>position</var> [ /Attribute=<var>irefAttr</var> ] [ /Baseposition=<var>basePos</var> ] [ [[Programmer_Guide/Command_Reference_Options/Silent|/Ilent]] ]
In this case, the option <code>/Delete</code> will cause the {{STX}} position to be deleted. Note that here, too, the <code>/Format</code> option is mandatory.

== Bulk processing ==
If you need to retrieve the internal references for a larger number of file positions, you may supply the respective positions in an {{STX}} [[Programmer_Guide/Concepts/Extended_table|extended table item]]. In this case, the ''iref'' for each position will be stored in a different field of the same table:
 <var>var</var> := IREF <var>xmlfile</var> <var>table</var> <var>posfld</var> <var>reffld</var> [ /Delete /Tagged ] [ /Baseposition=<var>basePos</var> ] [ [[Programmer_Guide/Command_Reference_Options/Silent|/Ilent]] ]

Here, <var>table</var> is your extended table. Both <var>posfld</var> and <var>reffld</var> must be the names of fields (i.e., columns) in your table <var>table</var>, <var>posfld</var> containing your file positions. The <code>IREF</code> command will store the ''iref'' for each position in the corresponding <var>reffld</var> entry. Note that you maye use the same field for <var>posfld</var> and <var>reffld</var>, but that this will cause the file positions ''to be deleted'', making it a shortcut for the <code>/Delete</code> flag.

;<code>/Delete</code>: If this option is supplied, or if <var>posFld</var> is the same as <var>refFld</var>, then the file positions are deleted.
;<code>/All|Tagged</code>: If the <code>/All</code> option is used, ''all'' table entries are used, be they tagged or untagged (this is the default). If, on the other hand, the <code>/Tagged</code> option is supplied, then only the tagged entries are used.

== Selecting an element ==

The <code>IREF</code> may also be used for positioning in a file, more precisely: for selecting an XML element identified by either an ''iref'', or by a file position. Note that, since ''iref'' strings start with a slash, extraodinary measures are needed not to have {{STX}} misunderstand an ''iref'' as a (possibly invalid) command option (see below).

 IREF /Select [ [[Programmer_Guide/Command_Reference_Options/Silent|/Ilent]] ] [[Programmer_Guide/Command_Reference_Options/-|/-]] <var>xmlfile</var> <var>iref</var> | <var>pos</var>

Select the element at the specified position (<var>pos</var>) or internal reference (<var>iref</var>).

;<var>iref</var>
:The internal reference of an existing element. Note that, since an ''iref'' starts with a slash, you must take care of {{STX}} not mixing it up with a command option. To exert this kind of care, either put the iref under single quotes - e.g. <code>'<var>iref</var>'</code> -, or ''after'' the options, separated from them by the "end of options" option, [[Programmer_Guide/Command_Reference_Options/-|/-]].
;<var>pos</var>
:The position of an existing element.
;<code>/Select</code>
:This option is mandatory.