Programmer Guide/Command Reference/IREF

The IREF command returns the internal reference (IREF) of the currently selected element of the supplied XML 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 IREF command will return the empty string.

Iref of the currently selected element

The basic form of the IREF command retrieves the iref of the currently selected element:

var := IREF xmlfile /Format [ /Attribute=irefAttr ] [ /Baseposition=basePos ] [ /Ilent ]

Note that the /Format option is mandatory.

Iref of a STx file position

When you supply an STx file position, position, the IREF command retrieves the iref of the element whose position you supplied

var := IREF xmlfile /Format position [ /Attribute=irefAttr ] [ /Baseposition=basePos ] [ /Ilent ]

In this case, the option /Delete will cause the STx position to be deleted. Note that here, too, the /Format 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 extended table item. In this case, the iref for each position will be stored in a different field of the same table:

var := IREF xmlfile table posfld reffld [ /Delete /Tagged ] [ /Baseposition=basePos ] [ /Ilent ]

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

/Delete

If this option is supplied, or if posFld is the same as refFld, then the file positions are deleted.

/All|Tagged

If the /All option is used, all table entries are used, be they tagged or untagged (this is the default). If, on the other hand, the /Tagged option is supplied, then only the tagged entries are used.

---

/All|Tagged

IREF xmlfile iref|pos /Select [ /I ]

Select the element at the specified position (pos) or internal reference (iref).

iref

The internal reference of an existing element.

pos

The position of an existing element.

/Select

This option is mandatory.

Please not that you must surround the ref argument with single quotes, otherwise it will be interpreted as an option.

<code>IREF '$#f' '$#aset' /Select</code>