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 an 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.
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 ] [ /Attribute=irefAttr ] [ /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
- If this option is supplied, or if posFld is the same as refFld, then the file positions are deleted.
- If the
/Alloption is used, all table entries are used, be they tagged or untagged (this is the default). If, on the other hand, the
/Taggedoption is supplied, then only the tagged entries are used.
Selecting an element
IREF 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, extraordinary measures are needed not to have STx misunderstand an iref as a (possibly invalid) command option (see below).
IREF /Select [ /Nocase ] [ /Attribute=irefAttr ] [ /Baseposition=basePos ] [ /Ilent ] /- xmlfile iref | pos
Select the element at the specified position (pos) or internal reference (iref).
- 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.
'iref'-, or after the options, separated from them by the "end of options" option, /-.
- The position of an existing element.
- This option is mandatory.
- ignore case (normally, iref strings are case-sensitive)
- The silent option causes mishaps to be reported as warnings, instead of errors.
- With the "end of options" option, you tell STx that there are no further options in the respective line of code. This means that any further arguments will be considered, well, plain arguments, even if they should start with a slash.
- normally, the attribute storing the iref path components is called ID. With the
/Attribute=option, you may specify a different such attribute.
- normally, an iref is considered absolute, i.e., starting at the root element of the respective XML file. With the
/Baseposition=option, you may specify the position of a different element to be considered the root for the iref path.