Programmer Guide/Command Reference/IREF: Difference between revisions

From STX Wiki
Jump to navigationJump to search
Line 12: Line 12:
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.
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.


== Others ==
== 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]] ]
  <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]] ]


<var>var</var> := IREF <var>xmlfile</var> /Select [ <var>iref</var> | <var>position</var> ] [ /Nocase ] [ /Attribute=<var>irefAttr</var> ]
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.
            [ /Baseposition=<var>basePos</var> ] [ [[Programmer_Guide/Command_Reference_Options/Silent|/Ilent]] ]


-----
''Important:'' If the <code>/Delete</code> option is specified, or if <var>posFld</var> is the same as </var>refFld</var>, then the positions are deleted.
Returns the internal reference (<code>IREF</code>) to the selected element or an empty string.


;<var>xmlfile</var>


 
-----
 
:The id of an XML file item.
 
;<var>/Format</var>
 
:This option is mandatory.
 
;<var>/I</var>
 
:If set, errors are suppressed, and warnings are generated instead.
 
<code><var>var</var> := IREF <var>xmlfile</var> <var>pos</var> /Format /Delete [ /I ]</code>
 
Returns the internal reference to the element at the position <var>pos</var> or an empty string. If /Delete is specified, the position is also deleted.
 
;<var>pos</var>
 
:The position of an element in the XML file <var>xmlfile</var>.
 
;<var>/Delete</var>
 
:This option is mandatory.
 
See the commands above for a description of the other parameters and options.
 
<code>IREF <var>xmlfile</var> <var>table</var> <var>posFld refFld</var> /Format /Delete /All|Tagged [ /I ]</code>
 
Stores the internal references to the element found at the positions in the field <var>posFld</var> in the field <var>refFld</var>. If /Delete is specified, or <var>posFld</var> is the same as <var>refFld</var>, then the positions are also deleted.
 
;<var>table</var>
 
:The id of an extended table.
 
;<var>posFld</var>
 
:The name of the field where the element positions are stored.
 
;<var>refFld</var>
 
:The name of the field where the IREFs should be stored. If this is the same as <var>posFld</var>, then the positions are deleted before being overwritten.


;<var>/All|Tagged</var>
;<var>/All|Tagged</var>

Revision as of 12:55, 8 April 2011

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.

Important: If the /Delete option is specified, or if posFld is the same as refFld, then the positions are deleted.


/All|Tagged
If /All is specified, all table entries are used (this is the default). If /Tagged is specified, then only the tagged entries are used.

See the commands above for a description of the other parameters and options.

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>
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Command_Reference/IREF&oldid=3214"

Navigation menu

Personal tools