Programmer Guide/Shell Items/File/SET FILE: Difference between revisions

Latest revision as of 09:55, 24 June 2019

File Item
INTRODUCING	NEW	SET	ATTRIBUTES	EXAMPLES

1 Binary File Commands
2 Finding Files on Disk
- 2.1 Finding Files: FIND
- 2.2 Finding Files: NEXT
3 Status File Commands
4 Text and Section File I/O
5 Locking / Unlocking File Items
6 XML Doctype
7 XML Element and Attribute Manipulation
8 XML Element Data Manipulation
- 8.1 XML: GETDATA
- 8.2 XML: SETDATA
9 XML Element Positions
- 9.1 XML: POSITION
10 XML Load & Save
- 10.1 XML: LOAD
- 10.2 XML: SAVE
11 XML Navigation And Searching
- 11.1 XML: FIND
- 11.2 XML: GOTO
  - 11.2.1 Example

Binary File Commands

Binary Files: `LIST`

SET bfile LIST table

table

A simple table.

Append one entry per binary file section to the table table. Each entry contains the size of the section value, the number of rows and columns, and the data type in the following format:

1|…|4 rows columns I16|I32|F32|F64

Binary Files: `LOAD`

SET bfile LOAD numitem section

`numitem`	The id of a numeric shell item. The format and type of this item is changed to match the requirements of the loaded section.
`section`	The index of the section to load.

Load a section from a binary file into a numeric shell item.

Binary Files: `SAVE`

SET bfile SAVE numitem [ section ] [ /1|2|3|4]

`numitem`	The id of a numeric shell item or an asterisk. If `numitem` is an asterisk and `section` ≥ 0, then the section is deleted. If `numitem` is an asterisk and `section` = `-1` then all sections are deleted.
`section`	The section index (`0`,`1`,…) of an existing section. Leave empty to append a section.
`/n`	For a new section, this option determines the format of the section: /1…I16, /2…I32, /3…F32, /4…F64 (the latter is the default). Note that this flag is ignored if the section already exists.

Save the numerical item data to a binary file section. If the section already exists, then the numerical data must be the same size as the section data (i.e. the same number of rows and columns).

You can delete an existing section with the command bfile SAVE * section . If section equals -1, all sections are deleted.

Finding Files on Disk

Finding Files: `FIND`

SET file FIND search [ /File | /Directory ]

The command FIND starts a new search for files or directories located in the current directory and matching the search string (a file or directory name containing normal Windows wildcards).

The command NEXT looks for the next file matching the search specified in the FIND command. Both commands return an error if no (more) matching files were found. If the return code (RC) is zero, a matching file was found and its name etc. can be accessed via the file item attributes. The file item file must be a list file item (see NEW FILE).

`search`	file or directory name to search for.
`/File` or `/Directory`	If the option `/F` is specified, files are searched for, if `/D` is specified, directories are searched for. The default is `/F`.

Finding Files: `NEXT`

SET file NEXT

The command NEXT looks for the next directory or file matching the search string specified in the FIND command (q.v.)

Status File Commands

These commands can be applied to a file system file item (also called dummy file item).

Status Files: `STATUS`

SET file STATUS path [ /Silent ]

Retrieve the status of file path. If the file path exists (on disk), all available status values are retrieved and can be accessed via the file-item attributes. The file item file must be of type file.

/Silent If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

Status Files: `DELETE`

SET file DELETE path [ /Silent ]

Delete the file path. The command will fail if file is not an actual file (but a directory, a file system file item, or the like).

/Silent If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

Status Files: `RENAME` and `COPY`

SET file RENAME|COPY path newpath [ /Silent ]

Rename or copy the file path. The file item file must be a file system file item (as opposed to a directory, a file system file item, and the like). The RENAME function can also be used to move a file into another directory or to another disk drive or network-directory (located on another computer). Note that the RENAME command will fail if the newpath already exists, whilst the COPY command will silently overwrite an existing target file.

/Silent If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

Text and Section File I/O

The SET FILE commands LIST, LOAD and SAVE access the content of files attached to file items of type TEXT or SECTION (see NEW FILE … /Text and NEW FILE … /Section). Note that you can also use the command WRITE to write data to a file item.

SET file cmd table [type name]

`cmd`	Either `LIST`, `LOAD` or `SAVE` (see below).
`table`	A table to load data into or read data from.
`type`	Either `TEXT` or `SECTION.`
`name`	A section name.

A section is defined by its type and a name, the latter being optional if there is only one section of the same type. Both are strings which may not contain the characters "$", "[" , "]", ";" or "'" (single quotes). The name may consist of more than one word.

Note that the mode in which the file is read or written is dependent on the flags passed to the NEW FILE command.

Text Files: `LIST`

SET file LIST table [ type|* name|* ]

Retrieve a list of sections from a section file (not applicable for other file item types). One table entry with the following format is created per section:

sectionType sectionName

`table`	The simple table to append the section list to.
`type`	The type of sections to list. If no type or an asterisk is specified , all sections are listed.
`name`	The name of the sections to list. If no name or an asterisk is specified, all sections of type `type` are listed.

Text Files: `LOAD`

The file item LOAD command loads the contents of a file into a table. Both LOAD variants support the /Silent option.

SET file LOAD table [ /Silent ]           // text file
SET file LOAD table type name [ /Silent ] // section file

Load the whole content of the file (in case of a text file) or of a section (in case of a section file), and append the loaded data to the table item table. If the table is an extended or a parameter table, please use the table FORMAT command to appropriately configure the input formatting options first.

`table`	A simple, extended or parameter table which will have data appended to it.
`type`	The section type to load. There is no default.
`name`	The name of the section to load. There is no default.
`/Silent`	If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

Note that you can load a CSV file by setting the delimiter of the table you are loading into. See Formatting_table_fields.

See load_a_file_into_a_table.sts in the script examples directory for a working example.

Text Files: `SAVE`

Save the contents of a shell table item into a file.

SET textFile SAVE table [ /Silent ]

Saves the content of the table item table to a TEXT file.

`table`	The table containing the text to save to file.
`/Silent`	If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

SET sectionFile SAVE table type [name] [ /Silent ]

Saves the content of the table item table to a section name of type type in a section file. Saving an empty table to a section will delete the section.

`table`	The table containing the text to save to file.
`type`	The type of the section (e.g. the section `[macro myTestMacro]` has the type `macro`). This parameter is mandatory.
`name`	The name of the section (e.g. the section `[macro myTestMacro]` has the name `myTestMacro`).
`/Silent`	If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

Text Files: `SYNC`

SET file SYNC

Write section file from memory to disk.

Locking / Unlocking File Items

The use of lock/unlock is only important, if a file item is (or may be) used by more than one thread. In STx shells, spu items and display item are running in their own thread.

SET file LOCK

Lock the file item file. The execution of the calling shell is stopped, until the file item can be locked. If locked, only the shell which locked it has access to its content. The file must be explicitly unlocked with the command UNLOCK. Always beware deadlocks.

SET file LOCK timeout

Try to lock the file item file, but wait only the specified time. This command returns 0 (success) if the lock request was successful within the timeout, and a non-zero error code if not. If the caller already holds the lock, the command will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting. The argument timeout specifies the maximum lock-timeout in milliseconds and must be a number greater than zero.

SET file UNLOCK

Unlock the file item file. Note: Its very important that for each successful LOCK an UNLOCK is called!

XML Doctype

The STx XML implementation supports an element type definition which is not directly compatible with the standard XML definition methods like DTD or XML Schema. If necessary we will add an interface to a standard in the future. The XML element definitions are created with the command SET xmlfile DOCTYPE … as documented below. All definition commands should be applied before the XML content is accessed. The sequence of definition commands must be finished with the command SET xmlfile DOCTYPE CLOSE to verify and initialize the element types. The element type definitions are not mandatory. They are applied during XML access only if available.

The following notes apply to the commands below:

If an element is derived from a parent element, it inherits all children, all attributes and the base and not-base element. All inherited definitions can be overridden in the derived element.
If a base element is defined, elements of type tag can only be added to a position below (inside) the base element or an element derived from the base element.
If a none-base element is defined, elements of type tag can not be added to a position below (inside) the none-base element or an element derived from the none-base element.
If an undefined element tag is used as argument (e.g. parent, base or in the child command) an element type tag is created automatically (and should be selected and configured later).
If children are set to invisible, all element below/inside the element are hidden
The default attribute visibility is used for undefined attributes and for attributes without visibility setting.
A valid definition sequence (i.e., the sequence of all DOCTYPE commands before DOCTYPE CLOSE) must consist of at least one element definition and the root and name assignment.

STx has a predefined DOCTYPE (defined in the stxconfig.xml file), which guarantees data integrity.

// A very basic doctype example
$#xml doctype name 'testdoctype'
$#xml doctype element root * * * * yes yes yes
$#xml doctype root root
$#xml doctype element elem * * * * yes yes yes
$#xml doctype attribute type yes all default string no yes
$#xml doctype close

`DOCTYPE ELEMENT`

SET xmlfile DOCTYPE ELEMENT tag [parent base nobase data vtag vchildren vattributes]

Create a new element type or select an element type (e.g. to define children or attributes). See Note 7.

`tag`	tag name of the element type
`parent`	tag name of the parent type or `*` if none (1) (4)
`base`	tag name of the base element or `*` (2) (4)
`nobase`	tag name of the not-base element or `*` (3) (4)
`data`	a string defining the type of the data section (currently unused)
`vtag`	show tag in dialogs (`no`> or `yes`)
`vchildren`	show children in dialogs (`no`> or `yes`) (5)
`vattributes`	default visibility of attributes in dialogs (`no`>, `yes` or `all`) (6)

`DOCTYPE CHILD`

SET xmlfile DOCTYPE CHILD tag minoccur maxoccur

Add a child element definition to the last created/selected element.

`tag`	tag name of the child element (4)
`minoccur`	minimum number of occurrences (must be ≥ 0 or `*` meaning 0 occurences)
`maxoccur`	maximum number of occurrences (must be ≥ minoccur or `*` meaning ℵ₀)

`DOCTYPE ROOT`

SET xmlfile DOCTYPE ROOT tag

Assign the type tag of the root element. The element type must have been defined (7).

`DOCTYPE NAME`

SET xmlfile DOCTYPE NAME anytext (7)

Assign the title/name of the element definition (7).

`DOCTYPE CLOSE`

SET xmlfile DOCTYPE CLOSE

Close definition sequence. Initialise and verify all types. This must be the last command of the definition sequence (7).

`VALIDATE`

SET xmlfile VALIDATE errorTable|* [testdoc /Insert] [/Recursive] [/Position /Children /Attributes] [/Showposition]

Validate the xmlfile's selected element using the defined doctype. If all tests are passed, or if no doctype is defined, it sets RC to 0. A simple table (errorTable) can be passed, to log errors in. The tests can be performed on either just the selected element or the selected element and all elements within it (/Recursive). The position (/Position), attributes (/Attributes) and the occurrence of children (/Children) can be tested. If a test document (testdoc) is passed, the test document's selected element is validated (instead of the xmlfile) using the xmlfile's doctype. If the option /Insert is used in conjunction with testdoc, the test document's selected element is validated as if it were inserted at the position of the xmlfile's selected element. If no options are given, the options /R/P/C/A are used by default. The option /Showposition modifies any error strings, prefixing the string with a position id (leading to e.g. &quote;P#54 ASeg has invalid attributes&quote;).

`errorTable`	A simple table in which to log errors.
`testdoc`	An XML shell-file to be tested against the defined DOCTYPE.

XML Element and Attribute Manipulation

All commands act on the selected element unless otherwise indicated. On loading an XML file, the selected element is set to the root element. Navigating through the file then selects different elements.

XML: `ADDELEMENT`

SET xmlfile ADDELEMENT ename|xmlSourceFile [aname avalue …] [/Before|After|Replace /In|Out /First|Last /Copy]

Create a new empty element with tag ename.

The element is inserted before (/Before) or after (/After, which is the default) the selected element of xmlfile or it replaces (/Replace) the selected element. Attribute assignments (aname avalue) can be specified to set element attributes on the fly.

If a doctype has been defined, the element's position and attributes are validated and the function fails if the parameters are invalid. Required attributes which were not passed are set to their default values.

When the option /Copy is used in conjunction with an xmlSourceFile (instead of an ename), the selected element of xmlSourceFile is added.

The navigation options are applied as follows: The option /Out is carried out before adding the element. The options /First or /Last are then performed. After the element is added, the /In option is carried out.

XML: `ADDFILE`

SET xmlfile ADDFILE source [/After|Before|Replace] [/In|Out] [/Delete] [/Children] [/Novalidate]

Copy the selected element from XML file-item source to xmlfile. The element is inserted before (/Before) or after (/After which is the default) the selected element of xmlfile, or it replaces the selected element (/Replace). If the option /Delete is specified, the copied element is removed from source and the next (source) element (if any) is selected. If no navigation option is specified, the added element is selected. Possible navigation options are /In (step into the added element, after add) and /Out (step out of current parent, before add).

`source`	The source XML file item to be added.
`/After`, `/Before` or `/Replace`	Insert the `source` file after or before the selected element, or replace the selected element.
`/In` or `Out`	Navigate out of the selected `xmlfile` element before add or navigate into the `xmlfile` selected element after add.
`/Delete`	Delete the sources selected element from the source file once it has been added.
`/Children`	If this flag is specified, all children of the current `source` element are added to the current element of the target file (as children). In this case all other options except `/Novalidate` are ignored!
`/Novalidate`	Disable validation (do not validate source data)

Note that if adding the file at root level, the root element will be replaced no matter what /A, /B and /R options are given.
Note that if the root element of the source document is added, the nodes on that level (e.g. the <?xml?> and <!DOCTYPE> entries) are not copied.

This function sets RC to 0 on success.

XML: `DOCTYPE ATTRIBUTE`

SET xmlfile DOCTYPE ATTRIBUTE name required visibility default type params

Add an attribute definition to the last created/selected element.

name attribute name

required attribute is required (yes or no)

visibility visibility of attribute in dialogs (no…hidden, yes…show value, all…show name and value)

default default value or * for no default

type, params

attribute data type and configuration parameters:

type	params
`INTEGER`	`minimum` `maximum`
`NUMBER`	`minimum` `maximum`
`STRING`	`respectcase` `unique`
`VALUELIST`	`value₁ value₂…`

minimum minimum value or * for infinite

maximum maximum value or * for infinite

respectcase respect (yes) or ignore (no) case in search/compare functions

unique value must be unique (yes) on the elements level or not (no)

value₁, value₂ possible values for a valuelist attribute

XML: `ADDNODE`

SET xmlfile ADDNODE text [aname avalue …] /Comment|DocType|Element|ProcInst [/Before|After|Replace /In|Out /First|Last]

Add a node to the XML-file. The node types supported are processing instructions (<?xml version="1.0"?>), elements (<item>data</item>), document types (<!DOCTYPE section SYSTEM "stx.dtd">) and comments (<!—comment -->). The text has a different meaning for each node type: for a processing instruction it is the target xml, for an element it is the tag item, for the document type it is the text between "<!DOCTYPE " and ">" and for a comment it is the text within the comment markers. Element nodes may be assigned attributes (aname avalue). The options /First and /Last navigate to the first or last node on this level (independent of the node type being added). If a doctype has been defined and the node is an element, the element's position and attributes are validated and the function fails if the parameters are invalid.

XML: `ADDTABLE`

SET xmlfile ADDTABLE table ename [/After|Before|Replace] [/In|Out /Data|Empty /Cdata] [/TagErrorsOnly]

Add the entries of table as elements to xmlfile. One element per entry is added, after (/After, which is the default) or before (/Before) the current element, or replacing (/Replace) the current element. The argument ename is used as the element tag. If /Data is specified, the entry data is stored in the element's data section using the table's write format, otherwise (/Empty is the default), the entry data is stored as element attributes (use field names as attribute names, does not store empty fields, uses the write format) and the element data section is empty. In conjunction with /Data, the option /Cdata can be used to create CData sections instead of normal data sections. There is a severe performance hit (1.300%) if you use the /Before option since indexes have to be recalculated.

`table`	A shell table with the entries to be added to the XML file. This parameter is mandatory.
`ename`	The string to be used as the created element's tag. This parameter is mandatory.
`/After`, `/Before` or `/Replace`	Specify whether the new elements should be added before (`/Before`) or after (`/A`) the selected element or if they even should replace the selected element (`/Replace`).
`/In` or `Out`	If specified, `/In` navigates into the selected element before the new element is added. If specified, `/Out` navigates out of the selected element after the new element has been added.
`/Data` or `/Empty`	If `/Data` is specified, then the entry is stored in the data section of the new element. Otherwise, the data is stored as attribute values.
`/Cdata`	Specify `/Cdata` if the data should be enclosed within a CData section.
`/TagErrorsOnly`	Specify if entries which cause errors should be tagged in the table but correct entries should be added. Otherwise, if one error occurs, no entries are added.

XML: `DELETEELEMENT`

SET xmlfile DELETEELEMENT [ename] [/Child]

Delete the selected element itself (no arguments) or delete all elements with the tag ename on the current level. If /Child is specified, the selected element's children are deleted, but not the selected element itself.

Warning: This operation can take a very long time!

SET xmlfile DELETEELEMENT table field [/Resetpos /Child /All|Tagged]

Delete all elements found at the positions stored in the column field of the table table.

`/Child`	If `/Child` is specified, the selected element's children are deleted, but not the selected element itself.
`/Resetpos`	The positions are deleted, but not the elements.
`/All`	All table entries are used. This is the default.
`/Tagged`	Only tagged entries are used.

XML: `EXTRACTFILE`

SET xmlfile EXTRACTFILE xmlSubDoc posAttrName [tag_N recursive_N … ]

Extract a selection of elements from a source xml file (xmlfile) into a target xml file (xmlSubDoc). The selection is dependent on the parameters tag_N and recursive_N and is independent of the selected element. The position of the extracted element in xmlfile is stored in the attribute posAttrName in the extracted element in xmlSubDoc. The original tree structure is retained. If no tag_N-names are given, then all positions in xmlSubDoc are removed from xmlfile and the contents of xmlSubDoc are deleted.

Note: the root element is always copied from xmlfile to xmlSubDoc. The pre-call contents (if any) are deleted from xmlSubDoc.

XML: `EXTRACTTABLE`

There are a number of different flavours of the EXTRACTTABLE command. The flavour used depends on the use of the /Mode flag.

SET xmlfile EXTRACTTABLE extTable posFld|* elemTag tagFld attr1Name attr1Fld … [ /P /R /1|All /Y]

Extract a selection of attribute values from elements with a specific tag on the current level into a table.

`extTable`	The id of an extended table item.
`posFld`	The name of the table field where element positions should be stored. If the option `/P` is specified, the position of the element's parent is save instead.
`elemTag`	The name of the element tag (e.g. "AFile" for <AFile> elements) or an asterisk for all elements.
`tagFld`	The name of the table field to store the extracted element tags.
`attr1Name`	The name of an attribute to extract.
`attr1Fld`	The name of the table field where the `attr1Name` attribute values should be stored.
`/Recursive`	If specified, the whole sub-tree is extracted.
`/Parent`	If specified, the element's parent's position is stored in the `posFld` column.
`/1` or `/All`	If `/1` is specified, elements are only extracted if any of the specified attributes are set. If `/All` is specified, elements are only extracted if all of the specified attributes are set. The default behaviour is to extract all elements irrespective of whether any attributes are set or not.
`/Y`	If specified, the `elemTag` argument is treated as a `DOCTYPE` class name and not only the elements, but also their derived classes are searched (e.g. if `elemTag` is `ASeg`, then all `APar`'s are searched too).

If positions are stored (i.e. posFld is not set to *) the programmer is responsible for deleting the positions.

SET xmlfile EXTRACTTABLE extTable elemTag₁ nameFld₁ … /Mode=Attributes /Y /Recursive

Saves a list of all the attributes found in the specified elements. The attributes of each element (elemTag_X) are stored in the associated table field nameFld_X.

/Mode=Attribute This is mandatory.

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

SET xmlfile EXTRACTTABLE extTable posFld|* tagFld attr1Name attr1Fld … /Mode=Read [/All|Tagged]

Updates the attribute list already in the table extTable. No new elements are searched (i.e. the existing positions are used).

`/Mode=Read`	This is mandatory.
`/All` or `/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 command above for a description of the other parameters and options.

XML: `ROOT`

SET xmlfile ROOT [*|tag] [aname avalue … ] [/Delete]

Name, rename or delete the root element tag, add, modify or delete the root element's attributes. An attribute is deleted if the value (avalue) passed is empty (>). If a doctype has been defined, the tag and attributes of the root element are validated and the function fails if the parameters are invalid. All required attributes which are not passed are automatically set to their default values.

`tag`	root element tag (e.g. '`STxDataSet`'). If an asterisk is specified, the root element tag is left unmodifed.
`aname`	An XML attribute name. Used in combination with the `avalue` parameter, this can set or delete a root element attribute.
`avalue`	A value to assign to the previous `aname` attribute. You can delete an attribute if this parameter is an empty string (e.g. `$#file root * CH` )
`/Delete`	If specified, the root element and all of the contained content is removed. If used in combination with `tag`, this option deletes the document and then creates a new root element.

Using the ROOT command invalidates all saved positions!

XML: `SETATTRIBUTE`

SET xmlfile SETATTRIBUTE aname avalue … [/Parent]

Set the attribute aname of the selected element to avalue. If /Parent is specified, the attributes of the parent element are modified instead of those of the selected element. Multiple attribute assignments (pairs of aname avalue) may be specified. An attribute is removed if an empty value is specified. If a doctype has been defined, the attributes are validated and the function fails if they are invalid.

Note: if the function fails, the pre-call state is not guaranteed (some attributes may have been set etc.).

The name of the attribute to set.
`avalue`	The value to set the attribute to.

SET xmlfile SETATTRIBUTE table field aname avalue …

The table table column field contains the positions of the elements who's attributes should be set.

`table`	The table item containing the positions of the elements where attribute should be set.
`field`	The table item field where element positions are stored.
`/Resetpos`	All element positions will be deleted after use.
`/All`	All table entries will be used. This is the default.
`/Tagged`	Only tagged entries will be used.
`/Value`	The `avalue` arguments are attribute values.
`/Fieldid`	The `avalue` arguments are table field names which contain attribute values.

SET xmlfile SETATTRIBUTE tag aname avalue … [/Y] [/Recursive]

Set all the attributes of tag elements on the current level.

`tag`	The tag identifying the elements to modify.
`/Y`	If the `/Y` option is used, the `tag` argument is used as a `DOCTYPE` class name, not an element tag. All derived classes are set too.
`/Recursive`	If specified, the command is carried out on the sub-tree as well.

XML: `SORT`

SET xmlfile SORT [attrID₀ dir₀ attriID_N dir_N] [/Delete]

Sort the children of the selected element according to the given attributes and directions and set the element's sort attribute. Previous sort attributes are overwritten. Calling this function without parameters re-sorts using the existing attributes. Calling the function without parameters but with the /Delete option removes the sort attributes. This function only supports attributes defined in the doctype. Note that if one of the attributes is unique (as defined in the doctype definition), only this attribute will be used to sort.

`attrId`	The name of an attribute defined in the doctype.
`dir`	The direction in which the elements should be sorted. The following values are allowed: `Ascending` and `Descending` (and any shorter version thereof, e.g. `Asc` or `Desc` or `a` or `d`) as well as `0` and `1`
`/Delete`	If no parameters are passed, the existing sort attributes are deleted.

The internal implementation works in the following way:

Unique Attributes: If one of the attributes passed to the SORT command is unique (as defined in the doctype), only this attribute is used for sorting. The elements are then sorted according to the direction and case is respected, if so defined in the doctype. All elements added to this level after sorting are added at the correct sorted position. Changing attributes of sorted elements also rearranges the sort order. If you have a large number of segments in an AFile, sorting according to a unique attribute is highly recommended, since the performance of the dataset validation is very bad for unsorted unique attributes. If you set the parent sort attribute by hand and want the sort to happen automatically, please set the unsorted attribute to 1. Now the next time an attribute is changed, or an element is added, all elements will first be sorted.
Non-unique Attributes: If the sort attributes are not unique, multiple attributes can be used. Elements added after sorting are not inserted at the correct position; instead, a further attribute unsorted is set in the parent element. Changing attributes after sorting does not affect the sort order – the parent attribute unsorted is set.
Validation: The VALIDATE command checks for sort attributes and sorts the elements before validation. When closing STx, the DataSet is validated, and therefore all elements with sort attributes are sorted.

Examples

$#xmlfile SORT ID Asc

The children of the selected element are sorted by their ID attribute in ascending order. The following command does the same by means of the SETATTRIBUTE command:

SET $#xmlfile SETATTRIBUTE sort 'ID Asc' unsorted '1'

When the selected element of $#xmlfile is an AFile, all ASegs in this AFile will be sorted according to their ID. Sorting will happen automatically, either on modification/addition of an element or attribute to one of the ASegs, or on validation.

XML Element Data Manipulation

Note: You cannot store data in the data section of an element with children!

XML: `GETDATA`

SET xmlfile GETDATA varname

Copy contents of XML data section into variable varname.

SET xmlfile GETDATA /Table table /Read

Empty table and copy contents of the XML data section into the table item table. This command loads data stored in the format generated by the command SET $#xmlfile SETDATA /T $#table.

SET xmlfile GETDATA /Table table [ firstField nFields ] /Numeric [/Vector]

Empty the table item table and copy the contents of the data section of the selected element into the numeric fields of the table. The GETDATA command loads data stored in the format set by the command SET $#xmlfile SETDATA /T/N $#table $#firstField $#nFields. Furthermore, it uses the attributes dim and vector set by the SETDATA command to ascertain the format of the data section. If the option /Vector is specified (see SETDATA below), it overrides the corresponding vector attribute if it exists.

XML: `SETDATA`

SET xmlfile SETDATA string [ /CData ]

string

The string to save in the element.

Set the data of the selected element to string. An empty string can be used to remove data (leading to an empty element). If the string contains characters which are reserved in the XML specification (e.g. <, >, &), the option /CData must be used, which will create a CData section.

SET xmlfile SETDATA /Table table [ /CData ]

`table`	The table containing the data to be stored in the element.
`/Table`	A mandatory option.

Store the content of table in the data section of the selected element (note: this is different from ADDTABLE, which adds one element per entry). The write format of the table is always used (see SET table FORMAT). If table contains characters which are reserved in the XML specification, the option /CData must be used.

SET xmlfile SETDATA /Table table [ firstField nfields ] /Numeric [ /Vector ]

`firstField`	The first field to extract data from.
`nFields`	The number of consecutive fields to extract data from.
`/Numeric`	A mandatory option.

Store the contents of table in the data section of the selected element. The table must be an extended table and the selected fields must be numeric! The values are stored as decimal numbers. The data is stored row-by-row (if no additional option is supplied) or column-by-column (if option /Vector is given). The attribute dim is automatically added to the selected element with the values "nRows nColumns". If the option /Vector is specified, the attribute vector is added with the value "1".

XML Element Positions

Element positions are unique ID strings which can be used like pointers or references to an element. The position of an element is saved with the command "#posvar := POSITION $#file" (see the command POSITION).

XML: `POSITION`

SET xmlfile POSITION [ parameters … ] [ /Silent ]

All POSITION commands support the /Silent option.

SET xmlfile POSITION pos /Restore [ /Silent ]

Select the element at position pos and delete the position.

SET xmlfile POSITION pos /Goto [ /Silent ]

Select the element at position pos but do not delete the position.

SET xmlfile POSITION [pos|*] /Delete [/Children] [ /Silent ]

Delete the position identified by pos. If pos is empty or an asterisk, then all saved positions for the selected element are deleted. If the option /Children is used, this position deletion is carried out recursively.

SET xmlfile POSITION pos₁ [pos₂] /Equal [ /Silent ]

Tests if the two positions pos₁ and pos₂ reference the same element (RC=0 for same element, RC=1 for different elements). If only one position (pos₁) is passed, this position is compared with that of the selected element.

XML Load & Save

XML: `LOAD`

SET xmlfile LOAD [path]

Load the document from the last selected or specified path and select the root element (previous content/position information is lost). If a path is specified, data are loaded from path and it is stored for later use, otherwise the stored path is used. The current content and all position and state settings are cleared before loading.

The function sets RC to 0 on success.

XML: SAVE

SET xmlfile SAVE [path]

Store (i.e., save to disk) the document in the supplied path or, if none is supplied, in the last selected path. If path is specified, it is also stored for later use.

XML Navigation And Searching

The following general navigation options can be supplied with any of the navigation, search and data processing command:

/In step into the selected element: set the selected element to the parent element and its first child to the selected element; this option is applied after successful execution of the navigation or manipulation function
/Out step out of the parent: set the element containing the current parent to the new parent and the current parent to the selected element; this option is applied before the function is executed
/First, /Last and /Next set the position to the first or last element of the current section (/First or /Last) or continue navigation/search (/Next); these options are applied before the respective function is executed (but after the /Out option).
/nodetype selects the type of the node to be found; the types /Element, /Processinginstruction, /Comment and /Doctype are supported

XML: `FIND`

SET xmlfile FIND

The FIND command searches an XML file for one, or more, occurences of a certain node. There are two variants of using the command:

consecutively searching for the first (SET xmlfile FIND /First), and any further occurence (SET xmlfile FIND /Next); or
searching for all occurrences in a single operation, returning them in an STx table (SET xmlfile FIND tableitem…)

Consecutive `FIND` operations

SET xmlfile FIND *|tag [ cexpr [ loper …]] [/In|Out /First|Next] [/Element|Processinginstruction|Doctype] [/Y]

Search for a node of the selected type (/Element which is the default, /Processinginstruction, /Doctype, see SET file GOTO) with the tag * or tag on the level of the selected element. For nodes of type element the arguments cexpr (conditional expression for attribute values, see the table below and loper (logical operator) are formatted and processed similarly to the SET table FIND function (e.g. attributename:<=:1000 or attributename:=I:a*.0*). Use the option /First (default) to begin search at the first element in the section, and /Next to start with the element following the selected element. If the node is found, it is selected, otherwise the selection remains unaffected. If the option /Y is specified, then tag is treated as a DOCTYPE class name, rather than an XML element tag (this means derived types are also recognised).

The shell variable RC is set to the integer 7 if the command was syntactically correct, but no element was found. The shell variable RC is set to the integer value 0 if an element corresponding to the search criteria was found.

Example

Find and delete the first element on the current level that has an ID attribute with a value of 3:

$#f find * 'ID:==:3' /First
if '$rc' == 0 $#f deleteelement

Returning all results in a table

SET xmlfile FIND postable posfield tag [ cexpr [ loper cexpr …]…] [/Recursive /Y]

Like the above FIND commands, except that the command does not return when it finds the first match, rather it saves the position of all matching elements in one field (posfield) of the specified table (postable). If the option /Recursive is specified, the whole sub-tree is searched. If the option /Y is specified, the tag string is treated as a DOCTYPE class name rather than an element tag, and all derived classes are searched.

`posTable`	The extended table where to store element positions.
`posField`	The extended table field in which to store element positions.

For all other parameters, please see the consecutive variant of the FIND command (above), and the table of cexpr expressions (below).

Example

// find all elements with a specific numerical attribute value
$#f find $#t $#tField $#elem '$#elemAttr:==:$#elemattrvalue' /Recursive

Find Conditions

format of cexpr description

attrname:cond

Check if a value is, or is not, assigned to an attribute. attrname is the name of the attribute (case sensitive!)

cond (=…is assigned, !…is not assigned)

attrname:cond:value

Check the value of an attribute. attrname is the name of the attribute (case sensitive!)

cond <, <=, ==, !=, >= or > value a number or numerical expression

attrname:cond:value

Match the value of an element's attribute

`attrname`	`cond`
name of the attribute (case sensitive!)	condition
`=I`	match, ignoring case
`!I`	do not match, ignoring case
`=R`	match respecting case
`!R`	do not match, respecting case
`mask`	match string, may contain wildcard characters

XML: `GOTO`

SET xmlfile GOTO [epath] [/First|Next|Last] [/In|Out] [/Element|Comment|Processinginstruction|Doctype] [/Reset]

Go to the first (/First, last (/Last) or next (/Next) element. If epath is specified, go to the first (/First, last (/Last) or next (/Next) element matching epath.

You can specify the type of node to navigate to with the options /Element, /Comment, /Processinginstruction and /Doctype, respectively. If only the node type option is used (without argument and other options), the first node of the respective type in the document is located.

The options /First, /Next and /Last only work with epath if epath does not contain slashes, i.e. if it specifies an element tag without an actual path (e.g. "elemtag"). For multi-level epaths like '*/elemtag' or '/root/elemtag/elemtag', the search finds the first element every time, and neither of /First, /Next and /Last should be supplied.

`epath`	The path of the element to go to. The normal format of `epath` is "`elemtag`". If you want to go to an element on a deeper level, the format is '`*/elemtag`'. The format of `epath` is absolute if it starts with the forward slash (e.g. '`/rootelem/firstelem`'). To ensure that `epath` is correctly interpreted, always enclose it in single quotation marks. XML is case sensitive, so `epath` must match exactly (wildcards are not supported). If no options are given, the current position is reset to the first child element of the root element.
`/First`, `/Next` or `/Last`	Determines whether to navigate to the first, last or next element. The default is `/Next`.
`/E`	Navigate to a data element node (e.g. `<elemtag>`)
`/C`	Navigate to an XML comment (e.g. `<!-- comment -->`). The argument `epath` is ignored.
`/P`	Navigate to an XML processing instruction (e.g. `<?pinst …?>`). The argument `epath` is used as the tag name of the processing instruction node.
`/Doctype`	Navigate to a document type (e.g. `<!DOCTYPE typename …>`). The argument `epath` is used for the name of the document type. The default is `/Element`.
`/Reset`	Reset the element selection. This means that no element is selected and a GOTO command with the option /Next will navigate to the first element.
`/In`	step into the selected element: set the selected element to the parent element and its first child to the selected element; this option is applied after successful execution of the navigation or manipulation function
`/Out`	step out of the parent: set the element containing the current parent to the new parent and the current parent to the selected element; this option is applied before the function is executed

Note that you can get yourself into difficulties if you use multiple options, e.g /i /f. Although you may feel inclined to think you are going to navigate in and go to the first element there, you will actually go to the first element and then navigate in.

You can use the file item attribute !XCHILDREN to determine if an element has children or not.

RC is set to 0 if the element is found and a value greater than 0 if not.

Example

// go to the root element <STxColorPalette>
$#xmlfile goto '/STxColorPalette'

@@ Line 1: / Line 1: @@
 {{DISPLAYTITLE:{{SUBPAGENAME}}}}
+{{File Item}}
 ==Binary File Commands==
-===LIST===
+=== Binary Files: <code>LIST</code> === <!-- C.G.: Headings must be unique within a Wiki document! -->
   SET <var>bfile</var> LIST <var>table</var>
@@ Line 14: / Line 15: @@
 |&hellip;|4 rows columns I16|I32|F32|F64
-===LOAD===
+===Binary Files: <code>LOAD</code> === <!-- C.G. headings must be unique! -->
-;<code>SET <var>bfile</var> LOAD <var>numitem</var> <var>section</var></code>:
+ SET <var>bfile</var> LOAD <var>numitem</var> <var>section</var>
-:;<var>numitem</var>: The id of a numeric shell item. The format and type of this item is changed to match the requirements of the loaded section.
+{|
-:;<var>section</var>: The index of the section to load.
+|-
+| <var>numitem</var>
+| The id of a numeric shell item. The format and type of this item is changed to match the requirements of the loaded section.
+|-
+| <var>section</var>
+| The index of the section to load.
+|}
 Load a section from a binary file into a numeric shell item.
-===SAVE===
+=== Binary Files: <code>SAVE</code> === <!-- C.G. headings must be unique! -->
-;<code>SET <var>bfile</var> SAVE <var>numitem</var> [ <var>section</var> ] [ /1|2|3|4]</code>:
+ SET <var>bfile</var> SAVE <var>numitem</var> [ <var>section</var> ] [ /1|2|3|4]
-:;<var>numitem</var>: The id of a numeric shell item or an asterisk. If <var>numitem</var> is an asterisk and <var>section</var> >= 0, then the section is deleted. If <var>numitem</var> is an asterisk and <var>section</var> = <code>-1</code> then all sections are deleted.
+{|
-:;<var>section</var>: The section index (<code>0</code>,<code>1</code>,...) or <code>-1</code> to append a section (default).
+|-
-:;option <var>/n</var>: This option selects the format of the section format: /1=I16, /2=I32, /3=F32, /4=F64 (default). Note that this flag is ignored if the section already exists.
+| <var>numitem</var>
+| The id of a numeric shell item or an asterisk. If <var>numitem</var> is an asterisk and <var>section</var>&nbsp;&ge;&nbsp;0, then the section is deleted. If <var>numitem</var> is an asterisk and <var>section</var>&nbsp;=&nbsp;<code>-1</code> then ''all'' sections are deleted.
+|-
+| <var>section</var>
+| The section index (<code>0</code>,<code>1</code>,&hellip;) of an existing section. Leave empty to append a section.
+|-
+| <code>/n</code>
+| For a new section, this option determines the format of the section: /1&hellip;I16, /2&hellip;I32, /3&hellip;F32, /4&hellip;F64 (the latter is the default). Note that this flag is ignored if the section already exists.
+|}
 Save the numerical item data to a binary file section. If the section already exists, then the numerical data must be the same size as the section data (i.e. the same number of rows and columns).
-You can delete an existing section with the command <code> <var>bfile</var> SAVE * <var>section</var> </code>. If <var>section</var> equals <code>-1</code>, all sections are deleted.
+You can delete an existing section with the command <code><var>bfile</var> SAVE * <var>section</var> </code>. If <var>section</var> equals <code>-1</code>, ''all'' sections are deleted.
 ==Finding Files on Disk==
-===FIND===
+=== Finding Files: <code>FIND</code> === <!-- C.G.: Headings must be unique within a Wiki page! -->
-<code>SET <var>file</var> FIND <var>search</var> [ /F|D ]</code>
+ SET <var>file</var> FIND <var>search</var> [ /File | /Directory ]
-The command <code>FIND</code> starts a new search for files or directories located in the current directory and matching the <var>search</var> string (= wildcard file or directory name).
+The command <code>FIND</code> starts a new search for files or directories located in the current directory and matching the <var>search</var> string (a file or directory name containing normal Windows wildcards).
-The command <code>NEXT</code> looks for the next file matching the <var>search</var> specified in the <code>FIND</code> command. Both commands return an error if no (more) matching files were found. If the return code (<code>RC</code>) is zero, a matching file was found and its name etc. can be accessed via the [[Programmer Guide/Shell Items/File/FILE Item Attributes|file item attributes]]. The file item <var>file</var> must be a list file item (see <code>NEW FILE</code>).
+The command <code>NEXT</code> looks for the next file matching the <var>search</var> specified in the <code>FIND</code> command. Both commands return an error if no (more) matching files were found. If the return code (<var>RC</var>) is zero, a matching file was found and its name etc. can be accessed via the [[Programmer Guide/Shell Items/File/FILE Item Attributes|file item attributes]]. The file item <var>file</var> must be a [[Programmer_Guide/Shell_Items/File/NEW_FILE#List_File_Items|list file item]] (see [[Programmer_Guide/Shell_Items/File/NEW_FILE#List_File_Items|<code>NEW FILE</code>]]).
-;<var>search</var>
+{|
+|-
-:A file or directory name to search for.
+| <var>search</var>
+| file or directory name to search for.
-;<var>/F|D</var>
+|-
+| <code>/File</code> or <code>/Directory</code>
+| If the option <code>/F</code> is specified, files are searched for, if <code>/D</code> is specified, directories are searched for. The default is <code>/F</code>.
+|}
-:If the option /F is specified, files are searched for, if /D is specified, directories are searched for. The default is /F.
+===Finding Files: <code>NEXT</code>=== <!-- C.G.: Headings must be unique within a Wiki page! -->
-===NEXT===
+ SET <var>file</var> NEXT
-<code>SET <var>file</var> NEXT</code>
+The command <code>NEXT</code> looks for the next directory or file matching the <var>search</var> string specified in the <code>FIND</code> command (q.v.)
-The command <code>NEXT</code> looks for the next directory or file matching the <var>search</var> string specified in the <code>FIND</code> command.
 ==Status File Commands==
-These commands can be executed by a status file item.
+These commands can be applied to a [[Programmer_Guide/Shell_Items/File/NEW_FILE#File_System_Items|file system file item]] (also called dummy file item).
-===STATUS===
+=== Status Files: <code id="STATUS">STATUS</code> === <!-- C.G. headings must be unique! -->
-<code>SET <var>file</var> STATUS <var>path</var> [ /S ]</code>
+ SET <var>file</var> STATUS <var>path</var> [ [[Programmer_Guide/Command_Reference_Options/Silent|/Silent]] ]
-Get status of file <var>path</var>. If the file <var>path</var> exists (on disk), all available status values are retrieved and can be accessed via the file-item attributes. The file item <var>file</var> must be of type file.
+Retrieve the status of file <var>path</var>. If the file <var>path</var> exists (on disk), all available status values are retrieved and can be accessed via the file-item attributes. The file item <var>file</var> must be of type ''file''.
-;<var>/S</var>
+{|
+|-
+| <code>/Silent</code>
+| If specified, errors will generate warning messages rather than error messages. See [[Programmer_Guide/Command_Reference_Options/Silent|The Silent Flag]] for details.
+|}
-:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
+=== Status Files: <code id="DELETE">DELETE</code> === <!-- C.G. headings must be unique! -->
-===DELETE===
+ SET <var>file</var> DELETE <var>path</var> [ [[Programmer_Guide/Command_Reference_Options/Silent|/Silent]] ]
-<code>SET <var>file</var> DELETE <var>path</var> [ /S ]</code>
+Delete the file <var>path</var>. The command will fail if <var>file</var> is not an actual file (but a directory, a file system file item, or the like).
-Delete the file <var>path</var>. The command will fail if <var>file</var> is not of type <code>file</code>.
+{|
+|-
+| <code>/Silent</code>
+| If specified, errors will generate warning messages rather than error messages. See [[Programmer_Guide/Command_Reference_Options/Silent|The Silent Flag]] for details.
+|}
-;<var>/S</var>
+=== Status Files: <code id="RENAME">RENAME</code> and <code id="COPY">COPY</code> === <!-- C.G. headings must be unique! -->
-:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
+ SET <var>file</var> RENAME|COPY <var>path</var> <var>newpath</var> [ [[Programmer_Guide/Command_Reference_Options/Silent|/Silent]] ]
-===RENAME and COPY===
+Rename or copy the file <var>path</var>. The file item <var>file</var> must be a file system file item (as opposed to a directory, a file system file item, and the like). The <code>RENAME</code> function can also be used to move a file into another directory or to another disk drive or network-directory (located on another computer). Note that the <code>RENAME</code> command will fail if the <var>newpath</var> already exists, whilst the <code>COPY</code> command will silently overwrite an existing target file.
-<code>SET <var>file</var> RENAME|COPY <var>path</var> <var>newpath</var> [ /S ]</code>
+{|
+|-
-Rename or copy the file <var>path</var>. The file item <var>file</var> must be of type file. The <code>RENAME</code> function can also be used to move a file into another directory or to another disk drive or network-directory (located on another computer). Note that the <code>RENAME</code> command will fail if the <var>newpath</var> already exists, whilst the <code>COPY</code> command with overwrite an existing file.
+| <code>/Silent</code>
+| If specified, errors will generate warning messages rather than error messages. See [[Programmer_Guide/Command_Reference_Options/Silent|The Silent Flag]] for details.
-;<var>/S</var>
+|}
-:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
 ==Text and Section File I/O==
-The <code>[[Programmer Guide/Macro Library/DOMODALDIALOG|SET FILE]]</code> commands <code>LIST</code>, <code>LOAD</code> and <code>SAVE</code> access the content of files attached to file items of type <code>TEXT</code> or <code>SECTION</code> (see <code>NEW FILE</code>). Note that you can also use the command <code>WRITE</code> to write data to a file item.
+The <code>SET FILE</code> commands <code>LIST</code>, <code>[[#Text_Files:_LOAD|LOAD]]</code> and <code>SAVE</code> access the content of files attached to file items of type <code>TEXT</code> or <code>SECTION</code> (see [[Programmer_Guide/Shell_Items/File/NEW_FILE#Text_Files|<code>NEW FILE &hellip; /Text</code>]] and [[Programmer_Guide/Shell_Items/File/NEW_FILE#Section_Files|<code>NEW FILE &hellip; /Section</code>]]). Note that you can also use the command [[Programmer_Guide/Command_Reference/WRITE|<code>WRITE</code>]] to write data to a file item.
-<code>SET <var>file</var> <var>cmd</var> <var>table</var> [<var>type</var> <var>name</var>]</code>
+ SET <var>file</var> <var>cmd</var> <var>table</var> [<var>type</var> <var>name</var>]
-;<var>cmd</var>
+{|
+|-
+| <var>cmd</var>
+| Either <code>LIST</code>, <code>LOAD</code> or <code>SAVE</code> (see below).
+|-
+| <var>table</var>
+| A table to load data into or read data from.
+|-
+| <var>type</var>
+| Either <code>TEXT</code> or <code>SECTION.</code>
+|-
+| <var>name</var>
+| A section name.
+|}
-:Either <code>LIST</code>, <code>LOAD</code> or <code>SAVE</code> (see below).
+A section is defined by its <var>type</var> and a <var>name</var>, the latter being optional if there is only one section of the same <var>type</var>. Both are strings which may not contain the characters "<code>$</code>", "<code>[</code>" , "<code>]</code>", "<code>;</code>" or "<code>'</code>" (single quotes). The <var>name</var> may consist of more than one word.
-;<var>table</var>
+Note that the mode in which the file is read or written is dependent on the flags passed to the <code>NEW FILE</code> command.
-:A table to load data into or read data from.
+=== Text Files: <code>LIST</code> === <!-- C.G. headings must be unique! -->
-;<var>type</var>
+ SET <var>file</var> LIST <var>table</var> [ <var>type</var>|* <var>name</var>|* ]
-:Either <code>TEXT</code> or <code>SECTION.</code>
+Retrieve a list of sections from a [[Programmer_Guide/Shell_Items/File/NEW_FILE#Section_Files|section file]] (not applicable for other file item types). One table entry with the following format is created per section:
-;<var>name</var>
+ sectionType sectionName
-:A section name.
+{|
+| <var>table</var>
+| The simple table to append the section list to.
+|-
+| <var>type</var>
+| The type of sections to list. If no type or an asterisk is specified , all sections are listed.
+|-
+| <var>name</var>
+| The name of the sections to list. If no name or an asterisk is specified, all sections of type <var>type</var> are listed.
+|}
-A section is defined by its <var>type</var> and a <var>name</var> (optional, if more than one section of the same <var>type</var> is used). Both id parts are strings which may not contain the characters '$', '[' , ']', ';' or ''' (single quotes). The <var>name</var> may consist of more than one word.
+=== Text Files: <code>LOAD</code> === <!-- C.G. headings must be unique! -->
-Note that the mode in which the file is read or written is dependant on the flags passed to the <code>NEW FILE</code> command.
+The file item <code>LOAD</code> command loads the contents of a file into a table. Both LOAD variants support the [[Programmer_Guide/Command_Reference_Options/Silent|/Silent]] option.
-===COPY===
+ SET <var>file</var> LOAD <var>table</var> [ /Silent ]           '''// text file'''
+ SET <var>file</var> LOAD <var>table</var> <var>type</var> <var>name</var> [ /Silent ] '''// section file'''
-<code>SET <var>fileItem</var> COPY /Z /E|D <var>sourceFile</var> [ <var>targetFile</var>|* [ <var>password</var>|* ]</code>
+Load the whole content of the file (in case of a [[Programmer_Guide/Shell_Items/File/NEW_FILE#Text_Files|text file]]) or of a section (in case of a [[Programmer_Guide/Shell_Items/File/NEW_FILE#Section_Files|section file]]), and append the loaded data to the table item <var>table</var>. If the table is an extended or a parameter table, please use the table [[Programmer_Guide/Shell_Items/Table/SET_TABLE#FORMAT|<code>FORMAT</code> command]] to appropriately configure the input formatting options first.
-Copy a source to a target file encrypting / decrypting it in the process.
+{|
+| <var>table</var>
-/E|D
+| A simple, extended or parameter table which will have data appended to it.
+|-
-:/E - Encrypt
+| <var>type</var>
+| The section type to load. There is no default.
-:/D - Decrypt
+|-
+| <var>name</var>
-===LIST===
+| The name of the section to load. There is no default.
+|-
-<code>SET <var>file</var> LIST <var>table</var> [ <var>type</var>|* <var>name</var>|* ]</code>
+| <code>/Silent</code>
+| If specified, errors will generate warning messages rather than error messages. See [[Programmer_Guide/Command_Reference_Options/Silent|The Silent Flag]] for details.
-Retrieve a list of sections from a file (only for <code>SECTION</code> file items). One table entry is created per section with the following format:
+|}
-<code>sectionType sectionName</code>
-;<var>table</var>
-:The simple table to append the section list to.
-;<var>type</var>
-:The type of sections to list. If no type or an asterisk is specified , all sections are listed.
-;<var>name</var>
-:The name of the sections to list. If no name or an asterisk is specified, all sections of type <var>type</var> are listed.
-===LOAD===
-The file item <code>LOAD</code> command loads the contents of a file into a table. Both LOAD variants support the /S option.
-<code>SET <var>file</var> LOAD <var>table</var> [ /S ] // text file</code>
-<code>SET <var>file</var> LOAD <var>table</var> <var>type</var> <var>name</var> [ /S ] // section file</code>
-Load the whole content of the file (<code>TEXT</code>) or a section (<code>SECTION</code>), and append to the table item <var>table</var>. If the table is an extended or parameter table, please use the table <code>FORMAT</code> command to configure the input formatting options.
-;<var>table</var>
-:A simple, extended or parameter table which will have data appended to it.
-;<var>type</var>
-:The section type to load. There is no default.
-;<var>name</var>
+Note that you can load a CSV file by setting the delimiter of the table you are loading into. See [[Programmer_Guide/Shell_Items/Table/SET_TABLE#Formatting_table_fields|Formatting_table_fields]].
-:The name of the section to load. There is no default.
-;<var>/S</var>
-:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
 See <code>load_a_file_into_a_table.sts</code> in the script examples directory for a working example.
-===SAVE===
+=== Text Files: <code>SAVE</code> === <!-- C.G. headings must be unique! -->
 Save the contents of a shell table item into a file.
-<code>SET <var>textFile</var> SAVE <var>table</var> [ /S ]</code>
+ SET <var>textFile</var> SAVE <var>table</var> [ [[Programmer_Guide/Command_Reference_Options/Silent|/Silent]] ]
 Saves the content of the table item <var>table</var> to a <code>TEXT</code> file.
-;<var>table</var>
+{|
+| <var>table</var>
+| The table containing the text to save to file.
+|-
+| <code>/Silent</code>
+| If specified, errors will generate warning messages rather than error messages. See [[Programmer_Guide/Command_Reference_Options/Silent|The Silent Flag]] for details.
+|}
-:The table containing the text to save to file.
+ SET <var>sectionFile</var> SAVE <var>table</var> <var>type</var> [<var>name</var>] [ [[Programmer_Guide/Command_Reference_Options/Silent|/Silent]] ]
-;<var>/S</var>
+Saves the content of the table item <var>table</var> to a section <var>name</var> of type <var>type</var> in a [[Programmer_Guide/Shell_Items/File/NEW_FILE#Section_Files|section file]]. Saving an empty table to a section will delete the section.
-:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
+{|
+| <var>table</var>
-<code>SET <var>sectionFile</var> SAVE <var>table</var> <var>type</var> [<var>name</var>] [ /S ]</code>
+| The table containing the text to save to file.
+|-
-Saves the content of the table item <var>table</var> to a <code>SECTION</code> file. Saving an empty table to a section will delete the section.
+| <var>type</var>
+| The type of the section (e.g. the section <code>[macro myTestMacro]</code> has the type <code>macro</code>). This parameter is mandatory.
-;<var>table</var>
+|-
+| <var>name</var>
-:The table containing the text to save to file.
+| The name of the section (e.g. the section <code>[macro myTestMacro]</code> has the name <code>myTestMacro</code>).
+|-
-;<var>type</var>
+| <code>/Silent</code>
+| If specified, errors will generate warning messages rather than error messages. See [[Programmer_Guide/Command_Reference_Options/Silent|The Silent Flag]] for details.
-:The name of the section type (e.g. the section <code>[macro myTestMacro]</code> has the type <code>macro</code>). This parameter is mandatory.
+|}
-;<var>name</var>
-:The name of the section (e.g. the section <code>[macro myTestMacro]</code> has the name <code>myTestMacro</code>).
-;<var>/S</var>
-:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
+=== Text Files: <code>SYNC</code> === <!-- C.G. headings must be unique! -->
-===SYNC===
+ SET <var>file</var> SYNC
-<code>SET <var>file</var> SYNC</code>
-Write section file from memory to disk
+Write section file from memory to disk.
 ==Locking / Unlocking File Items==
-===LOCK===
+The use of '''lock/unlock''' is only important, if a file item is (or may be) used by more than one thread. In {{STX}} shells, spu items and display item are running in their own thread.
-<code>SET <var>file</var> LOCK</code>
-Lock the file item. If locked, only the shell which locked it has access to its content. The file must be unlocked after finishing the 'critical' processing section.
-===TRYLOCK===
-<code>SET <var>file</var> TRYLOCK [ <var>timeout</var> ] [ /S ]</code>
-Try to lock the file item <var>file</var>. If no timeout is specified, <code>TRYLOCK</code> returns immediately. If the caller already *holds* the lock, <code>TRYLOCK</code> will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting.
-;<var>timeout</var>
-:If specified, <code>TRYLOCK</code> will try to get a lock once per millisecond until it is either successful, or <var>timeout</var> milliseconds have elapsed.
-;<var>/S</var>
-:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
-Return Codes:
-<code>0</code> - an unlocked file has been successfully locked.
-<code>348</code> - Error: if the file item could not be locked due to it being locked by someone else.
-<code>349</code> - Error: if the file item could not be locked due to it being locked by the caller.
-Example:
+ SET <var>file</var> LOCK
+Lock the file item <var>file</var>. The execution of the calling shell is stopped, until the file item can be locked. If locked, only the shell which locked it has access to its content. The file must be explicitly unlocked with the command <code>UNLOCK</code>. Always beware deadlocks.
-"<code>SET $#file TRYLOCK 5000</code>" will try hard to lock the file. If it does not succeed within 5000ms (i.e., five seconds), it will fail - but it will not fail earlier.
+ SET <var>file</var> LOCK <var>timeout</var>
+Try to lock the file item <var>file</var>, but wait only the specified time. This command returns '''0''' (success) if the lock request was successful within the timeout, and a non-zero error code if not. If the caller already ''holds'' the lock, the command will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting. The argument <var>timeout</var> specifies the maximum lock-timeout in milliseconds and must be a number greater than zero.
-The <code>TRYLOCK</code> command is intended for safe multithreading without race conditions occurring
+ SET <var>file</var> UNLOCK
+Unlock the file item <var>file</var>. '''Note''': Its very important that for each successful <code>LOCK</code> an <code>UNLOCK</code> is called!
-===UNLOCK===
-<code>SET <var>file</var> UNLOCK</code>
-Unlock the file item.
 ==XML Doctype==
-The {{STX}} XML implementation supports an element type definition which is not directly compatible with the standard XML definition methods like DTD or XML Schema. If necessary we will program an interface to a standard in the future. The XML element definitions are created with the command "<code>SET xmlfile DOCTYPE ...</code>" as documented below. All definition commands should be applied before the XML content is accessed. The sequence of definition commands must be finished with the command <code>SET xmlfile DOCTYPE CLOSE</code> to verify and initialize the element types. The element type definitions are not required and are applied during XML access only if available.
+The {{STX}} XML implementation supports an element type definition which is not directly compatible with the standard XML definition methods like DTD or XML Schema. If necessary we will add an interface to a standard in the future. The XML element definitions are created with the command <code>SET xmlfile DOCTYPE&nbsp;&hellip;</code> as documented below. All definition commands should be applied before the XML content is accessed. The sequence of definition commands must be finished with the command <code>SET xmlfile DOCTYPE CLOSE</code> to verify and initialize the element types. The element type definitions are not mandatory. They are applied during XML access only if available.
 The following notes apply to the commands below:
+* If an element is derived from a parent element, it inherits all children, all attributes and the base and not-base element. All inherited definitions can be overridden in the derived element.
+* If a base element is defined, elements of type tag can only be added to a position below (inside) the base element or an element derived from the base element.
+* If a none-base element is defined, elements of type tag can not be added to a position below (inside) the none-base element or an element derived from the none-base element.
+* If an undefined element tag is used as argument (e.g. parent, base or in the child command) an element type tag is created automatically (and should be selected and configured later).
+* If children are set to invisible, all element below/inside the element are hidden
+* The default attribute visibility is used for undefined attributes and for attributes without visibility setting.
+* A valid definition sequence (i.e., the sequence of all <code>DOCTYPE</code> commands before <code>DOCTYPE CLOSE</code>) must consist of at least one element definition and the root and name assignment.
-*If an element is derived from a parent element, it inherits all children, all attributes and the base and not-base element. All inherited definitions can be overridden in the derived element.
+{{STX}} has a predefined <code>DOCTYPE</code> (defined in the <code>stxconfig.xml</code> file), which guarantees data integrity.
-*If a base element is defined, elements of type tag can only be added to a position below (inside) the base element or an element derived from the base element.
-*If a none-base element is defined, elements of type tag can not be added to a position below (inside) the none-base element or an element derived from the none-base element.
-*If an undefined element tag is used as argument (e.g. parent, base or in the child command) an element type tag is created automatically (and should be selected and configured later).
+ // A very basic doctype example
+ $#xml doctype name 'testdoctype'
+ $#xml doctype element root * * * * yes yes yes
+ $#xml doctype root root
+ $#xml doctype element elem * * * * yes yes yes
+ $#xml doctype attribute type yes all default string no yes
+ $#xml doctype close
-*If children are set to invisible, all element below/inside the element are hidden
+===<code>DOCTYPE ELEMENT</code>===
-*The default attribute visibility is used for undefined attributes and for attributes without visibility setting.
+ SET <var>xmlfile</var> DOCTYPE ELEMENT <var>tag</var> [<var>parent</var> <var>base</var> <var>nobase</var> <var>data</var> <var>vtag</var> <var>vchildren</var> <var>vattributes</var>]
-*A valid definition sequence (= all DOCTYPE commands before <code>DOCTYPE CLOSE</code>) must consist of at least one element definition and the root and name assignment.
+Create a new element type or select an element type (e.g. to define children or attributes). See [[Note 7]]. <!-- WTF is Note 7? -->
-The application {{STX}} has a predefined DOCTYPE (defined in the stxconfig.xml file), which guarantees data integrity.<pre>
-// A very basic doctype example
-$#xml doctype name 'testdoctype'
-$#xml doctype element root * * * * yes yes yes
-$#xml doctype root root
-$#xml doctype element elem * * * * yes yes yes
-$#xml doctype attribute type yes all default string no yes
-$#xml doctype close
-</pre>
-===DOCTYPE ELEMENT===
-<code>SET <var>xmlfile</var> DOCTYPE ELEMENT <var>tag</var> [<var>parent base nobase data vtag vchildren vattributes</var>]</code>
-Create a new element type or select an element type (e.g. to define children or attributes). See Note 7.
 {|
 |-
-|tag
+|<var>tag</var>
 |tag name of the element type
 |-
-|parent
+|<var>parent</var>
-|tag name of the parent type or * if none (1)(4)
+|tag name of the parent type or <code>*</code> if none [[Note 1|(1)]] [[Note 4|(4)]] <!-- WTF? -->
 |-
-|base
+|<var>base</var>
-|tag name of the base element or <code>*</code> (2)(4)
+|tag name of the base element or <code>*</code> [[Note 2|(2)]] [[Note 4|(4)]] <!-- WTF? -->
 |-
-|nobase
+|<var>nobase</var>
-|tag name of the not<nowiki>-</nowiki>base element or <code>*</code> (3)(4)
+|tag name of the not<nowiki>-</nowiki>base element or <code>*</code> [[Note 3|(3)]] [[Note 4|(4)]] <!-- WTF? -->
 |-
-|data
+|<var>data</var>
 |a string defining the type of the data section (currently unused)
 |-
-|vtag
+|<var>vtag</var>
-|show tag in dialogs {no<nowiki>|</nowiki>yes}
+|show tag in dialogs (<code>no</code>> or <code>yes</code>)
 |-
-|vchildren
+|<var>vchildren</var>
-|show children in dialogs {no<nowiki>|</nowiki>yes}(5)
+|show children in dialogs (<code>no</code>> or <code>yes</code>) [[Note 5|(5)]] <!-- WTF? -->
 |-
-|vattributes
+|<var>vattributes</var>
-|default visibility of attributes in dialogs {<code>no</code>|<code>yes</code>|<code>all</code>} (6)
+|default visibility of attributes in dialogs (<code>no</code>>, <code>yes</code> or <code>all</code>) [[Note 6|(6)]] <!-- WTF? -->
 |}
+===<code>DOCTYPE CHILD</code>===
+ SET <var>xmlfile</var> DOCTYPE CHILD <var>tag</var> <var>minoccur</var> <var>maxoccur</var>
-===DOCTYPE CHILD===
-<code>SET <var>xmlfile</var> DOCTYPE CHILD <var>tag minoccur maxoccur</var></code>
 Add a child element definition to the last created/selected element.
@@ Line 332: / Line 298: @@
 {|
 |-
-|tag
+|<var>tag</var>
-|tag name of the child element (4)
+|tag name of the child element [[Note 4|(4)]] <!-- WTF? -->
 |-
-|minoccur
+|<var>minoccur</var>
-|minimum number of occurrences (>= 0 or <code>*</code>=0)
+|minimum number of occurrences (must be &ge;&nbsp;0 or <code>*</code> meaning 0 occurences)
 |-
-|maxoccur
+|<var>maxoccur</var>
-|maximum number of occurrences (>=minoccur or <code>*</code> for infinite)
+|maximum number of occurrences (must be &ge;&nbsp;minoccur or <code>*</code> meaning &alefsym;<sub>0</sub>)
 |}
+===<code>DOCTYPE ROOT</code>===
+ SET <var>xmlfile</var> DOCTYPE ROOT <var>tag</var>
-===DOCTYPE ROOT===
+Assign the type tag of the root element. The element type must have been defined [[Note 7|(7)]]. <!-- WTF? -->
-<code>SET <var>xmlfile</var> DOCTYPE ROOT <var>tag</var></code>
+===<code>DOCTYPE NAME</code>===
-Assign the type tag of the root element. The element type must already be defined (7).
+ SET <var>xmlfile</var> DOCTYPE NAME <var>anytext</var> [[Note 7|(7)]] <!-- WTF? -->
-===DOCTYPE NAME===
+Assign the title/name of the element definition  [[Note 7|(7)]]. <!-- WTF? -->
-<code>SET <var>xmlfile</var> DOCTYPE NAME <var>anytext</var> (7)</code>
+===<code>DOCTYPE CLOSE</code>===
-Assign the title/name of the element definition (7).
+ SET <var>xmlfile</var> DOCTYPE CLOSE
-===DOCTYPE CLOSE===
+Close definition sequence. Initialise and verify all types. This must be the last command of the definition sequence [[Note 7|(7)]]. <!-- WTF? -->
-<code>SET <var>xmlfile</var> DOCTYPE CLOSE</code>
+===<code>VALIDATE</code>===
-Close definition sequence. Initialise and verify all types. This must be the last command of the definition sequence (7).
+ SET <var>xmlfile</var> VALIDATE <var>errorTable</var>|<var>*</var> [<var>testdoc</var> /Insert] [/Recursive] [/Position /Children /Attributes] [/Showposition]
-===VALIDATE===
+Validate the <var>xmlfile</var>'s selected element using the defined doctype. If all tests are passed, or if no doctype is defined, it sets <var>RC</var> to <samp>0</samp>. A simple table (<var>errorTable</var>) can be passed, to log errors in. The tests can be performed on either just the selected element or the selected element and all elements within it (<code>/Recursive</code>). The position (<code>/Position</code>), attributes (<code>/Attributes</code>) and the occurrence of children (<code>/Children</code>) can be tested. If a test document (<var>testdoc</var>) is passed, the test document's selected element is validated (instead of the <var>xmlfile</var>) using the <var>xmlfile</var>'s doctype. If the option <code>/Insert</code> is used in conjunction with <var>testdoc</var>, the test document's selected element is validated as if it were inserted at the position of the <var>xmlfile</var>'s selected element. If no options are given, the options <code>/R/P/C/A</code> are used by default. The option <code>/Showposition</code> modifies any error strings, prefixing the string with a position id (leading to e.g. &quote;<code>P#54 ASeg has invalid attributes</code>&quote;).
-<code>SET <var>xmlfile</var> VALIDATE <var>errorTable</var>|<var>*</var> [<var>testdoc</var> /Insert] [/Recursive] [/Position /Children /Attributes] [/Showposition]</code>
+{|
+| <var>errorTable</var>
-Validate the <var>xmlfile</var>'s selected element using the defined doctype. If no doctype is defined, it returns true. If all tests are passed, it returns true. A simple table (<var>errorTable</var>) can be passed, to log errors in. The tests can be performed on either just the selected element or the selected element and all elements within it (/R). The position (/P), attributes (/A) and the occurrence of children (/C) can be tested. If a test document (<var>testdoc</var>) is passed, the test document's selected element is validated (instead of the <var>xmlfile</var>) using the <var>xmlfile</var>'s doctype. If the options /Insert is used in conjunction with <var>testdoc</var>, the test document's selected element is validated as if it were inserted at the position of the <var>xmlfile</var>'s selected element. If no options are given, the options /R/P/C/A are used by default. The option /S modifies any error strings, prefixing the string with a position id (e.g. '<code>P#54 ASeg has invalid attributes</code>').
+| A simple table in which to log errors.
+|-
-;<var>errorTable</var>
+| <var>testdoc</var>
+| An XML shell-file to be tested against the defined DOCTYPE.
-:A simple table in which to log errors.
+|}
-;<var>testdoc</var>
-:An XML shell-file to be tested against the defined DOCTYPE.
 ==XML Element and Attribute Manipulation==
-All commands act on the 'selected' element unless otherwise indicated. On loading an XML file, the selected element is set to the root element. Navigating through the file then selects different elements.
+All commands act on the ''selected'' element unless otherwise indicated. On loading an XML file, the selected element is set to the root element. Navigating through the file then selects different elements.
-===ADDELEMENT===
+===XML: <code id="ADDELEMENT">ADDELEMENT</code>===
-<code>SET <var>xmlfile</var> ADDELEMENT <var>ename</var>|<var>xmlSourceFile</var> [<var>aname avalue</var> ..] [/Before|After|Replace /In|Out /First|Last /Copy]</code>
+ SET <var>xmlfile</var> ADDELEMENT <var>ename</var>|<var>xmlSourceFile</var> [<var>aname</var> <var>avalue</var> &hellip;] [/Before|After|Replace /In|Out /First|Last /Copy]
 Create a new empty element with tag <var>ename</var>.
-The element is inserted before (/Before) or after (/After = default) the selected element of <var>xmlfile</var> or it replaces (/Replace) the selected element. Attribute assignments (<var>aname avalue</var>) can be specified to set element attributes.
+The element is inserted ''before'' (<code>/Before</code>) or ''after'' (<code>/After</code>, which is the default) the selected element of <var>xmlfile</var> or it ''replaces'' (<code>/Replace</code>) the selected element. Attribute assignments (<code><var>aname</var> <var>avalue</var></code>) can be specified to set element attributes on the fly.
-If a doctype has been defined, the element's position and attributes are validated and the function fails if the parameters are invalid. Required attributes which were not passed, are set to their default values.
+If a doctype has been defined, the element's position and attributes are validated and the function fails if the parameters are invalid. Required attributes which were not passed are set to their default values.
-When the option /C is used in conjunction with an <var>xmlSourceFile</var> (instead of an <var>ename</var>), the selected element of <var>xmlSourceFile</var> is added.
+When the option <code>/Copy</code> is used in conjunction with an <var>xmlSourceFile</var> (instead of an <var>ename</var>), the selected element of <var>xmlSourceFile</var> is added.
-The navigation options are applied as follows: The option /Out is carried out before adding the element. The options /First|Last are then performed. After the element is added, the /In option is carried out.
+The navigation options are applied as follows: The option <code>/Out</code> is carried out ''before'' adding the element. The options <code>/First</code> or <code>/Last</code> are then performed. After the element is added, the <code>/In</code> option is carried out.
-===ADDFILE===
+===XML: <code id="ADDFILE">ADDFILE</code>===
-<code>SET <var>xmlfile</var> ADDFILE <var>source</var> [/After|Before|Replace] [/In|Out] [/Delete] [/Children] [/Novalidate]</code>
+ SET <var>xmlfile</var> ADDFILE <var>source</var> [/After|Before|Replace] [/In|Out] [/Delete] [/Children] [/Novalidate]
-Copy the selected element from XML file-item <var>source</var> to <var>xmlfile</var>. The element is inserted before (/Before) or after (/After = default) the selected element of <var>xmlfile</var> or it replaces the selected element (/Replace). If the option /Delete is specified, the copied element is removed from <var>source</var> and the next (souce) element (if any) is selected. If no navigation option is specified, the added element is selected. Possible navigation options are /In (step into the added element, after add) and /Out (step out of current parent, before add).
+Copy the selected element from XML file-item <var>source</var> to <var>xmlfile</var>. The element is inserted ''before'' (<code>/Before</code>) or ''after'' (<code>/After</code> which is the default) the selected element of <var>xmlfile</var>, or it ''replaces'' the selected element (<code>/Replace</code>). If the option <code>/Delete</code> is specified, the copied element is removed from <var>source</var> and the next (source) element (if any) is selected. If no navigation option is specified, the added element is selected. Possible navigation options are <code>/In</code> (step into the added element, ''after'' add) and <code>/Out</code> (step out of current parent, ''before'' add).
-;<var>source</var>
+{|
+| <var>source</var>
-:The source XML file item to be added.
+| The source XML file item to be added.
+|-
-;<var>/After|Before|Replace</var>
+| <code>/After</code>, <code>/Before</code> or <code>/Replace</code>
+| Insert the <var>source</var> file after or before the selected element, or replace the selected element.
-:Insert the <var>source</var> file after or before the selected element, or replace the selected element.
+|-
+| <code>/In</code> or <code>Out</code>
-;<var>/In|Out</var>
+| Navigate out of the selected <var>xmlfile</var> element before add or navigate into the <var>xmlfile</var> selected element after add.
+|-
-:Navigate out of the selected <var>xmlfile</var> element before add or navigate into the <var>xmlfile</var> selected element after add.
+| <code>/Delete</code>
+| Delete the sources selected element from the source file once it has been added.
-;<var>/Delete</var>
+|-
+| <code>/Children</code>
-:Delete the sources selected element from the source file once it's been added.
+| If this flag is specified, all children of the current <var>source</var> element are added to the current element of the target file (as children). In this case all other options except <code>/Novalidate</code> are ignored!
+|-
-;<var>/Children</var>
+| <code>/Novalidate</code>
+| Disable validation (do not validate source data)
-:If this flag is specified, all children of the current sourcefile element are added to the current element of the target file (as children). In this case all other options except /Novalidate are ignored!
+|}
-;<var>/Novalidate</var>
-:Disable validation (do not validate source data)
+* Note that if adding the file at root level, the root element will be replaced no matter what <code>/A</code>, <code>/B</code> and <code>/R</code> options are given.
+* Note that if the root element of the source document is added, the nodes on that level (e.g. the <code>&lt;?xml?&gt;</code> and <code>&lt;!DOCTYPE&gt;</code> entries) are not copied.
-Note that if adding the file at root level, the root element will be replaced no matter what /A|B|R options are given. Note that if the root element of the source document is added, the nodes on that level (e.g. the <?xml?> and <!DOCTYPE> entries) are not copied.
+This function sets <var>RC</var> to <samp>0</samp> on success.
-===DOCTYPE ATTRIBUTE===
+===XML: <code id="DOCTYPE_ATTRIBUTE">DOCTYPE ATTRIBUTE</code>===
-<code>SET <var>xmlfile</var> DOCTYPE ATTRIBUTE <var>name required visibility default type params</var></code>
+ SET <var>xmlfile</var> DOCTYPE ATTRIBUTE <var>name</var> <var>required</var> <var>visibility</var> <var>default</var> <var>type</var> <var>params</var>
 Add an attribute definition to the last created/selected element.
@@ Line 434: / Line 397: @@
 {|
 |-
-|name
+|<var>name</var>
 |attribute name
 |-
-|required
+|<var>required</var>
-|attribute is required (<code>yes</code>|<code>no</code>)
+|attribute is required (<code>yes</code> or <code>no</code>)
 |-
-|visibility
+|<var>visibility</var>
-|visibility of attribute in dialogs (<code>no</code> = hidden, <code>yes</code> = show value, <code>all</code> = show name and value)
+|visibility of attribute in dialogs (<code>no</code>&hellip;hidden, <code>yes</code>&hellip;show value, <code>all</code>&hellip;show name and value)
 |-
-|default
+|<var>default</var>
 |default value or <code>*</code> for no default
 |-
-|type, params
+|<var>type</var>, <var>params</var>
-|attribute data type and configuration parameters:{|
+|attribute data type and configuration parameters:
+{|
 |-
 |type
@@ Line 453: / Line 417: @@
 |-
 |<code>INTEGER</code>
-|minimum maximum
+|<var>minimum</var> <var>maximum</var>
 |-
 |<code>NUMBER</code>
-|minimum maximum
+|<var>minimum</var> <var>maximum</var>
 |-
 |<code>STRING</code>
-|respectcase unique
+|<var>respectcase</var> <var>unique</var>
 |-
 |<code>VALUELIST</code>
-|value1 value2 ...
+|<code><var>value<sub>1</sub></var> <var>value<sub>2</sub></var>&hellip;</code>
 |}
 |-
-|minimum
+|<var>minimum</var>
 |minimum value or <code>*</code> for infinite
 |-
-|maximum
+|<var>maximum</var>
 |maximum value or <code>*</code> for infinite
 |-
-|respectcase
+|<var>respectcase</var>
 |respect (<code>yes</code>) or ignore (<code>no</code>) case in search/compare functions
 |-
-|unique
+|<var>unique</var>
 |value must be unique (<code>yes</code>) on the elements level or not (<code>no</code>)
 |-
-|value1, value2
+|<var>value<sub>1</sub></var>, <var>value<sub>2</sub></var>
-|possible values of a valuelist attribute
+|possible values for a valuelist attribute
 |}
+===XML: <code id="ADDNODE">ADDNODE</code>===
+ SET xmlfile ADDNODE <var>text</var> [<var>aname</var> <var>avalue</var> &hellip;] /Comment|DocType|Element|ProcInst [/Before|After|Replace /In|Out /First|Last]
-===ADDNODE===
+Add a node to the XML-file. The node types supported are ''processing instructions'' (<code>&lt;?xml version="1.0"?&gt;</code>), ''elements'' (<item>data</item>), ''document types'' (<code>&lt;!DOCTYPE section SYSTEM "stx.dtd"&gt;</code>) and ''comments'' (<code>&lt;!—comment --&gt;</code>). The <var>text</var> has a different meaning for each node type: for a processing instruction it is the target ''xml'', for an element it is the tag ''item'', for the document type it is the text between "<code>&lt;!DOCTYPE </code>" and "<code>&gt;</code>" and for a comment it is the text within the comment markers. Element nodes may be assigned attributes (<code><var>aname</var> <var>avalue</var></code>). The options <code>/First</code> and <code>/Last</code> navigate to the first or last node on this level (independent of the node type being added). If a doctype has been defined and the node is an element, the element's position and attributes are validated and the function fails if the parameters are invalid.
-<code>SET xmlfile ADDNODE <var>text</var> [<var>aname avalue</var> ...] /Comment|DocType|Element|ProcInst [/Before|After|Replace /In|Out /First|Last]</code>
+===XML: <code id="ADDTABLE">ADDTABLE</code>===
-Add a node to the XML-file. The node types supported are 'processing instructions' (<?xml version="1.0"?>), 'elements' (<item>data</item>), 'document types' (<!DOCTYPE section SYSTEM "stx.dtd">) and 'comments' (<!—comment -->). The <var>text</var> has a different meaning for each node type: for a processing instruction it is the target 'xml', for an element it is the tag 'item', for the document type it is the text between '<!DOCTYPE ' and '>' and for a comment it is the text within the comment markers. Element nodes may be assigned attributes (<var>aname avalue</var>). The options /First|Last navigate to the first or last node on this level (independent of the node type being added). If a doctype has been defined and the node is an element, the element's position and attributes are validated and the function fails if the parameters are invalid.
+ SET <var>xmlfile</var> ADDTABLE <var>table</var> <var>ename</var> [/After|Before|Replace] [/In|Out /Data|Empty /Cdata] [/TagErrorsOnly]
-===ADDTABLE===
+Add the entries of <var>table</var> as elements to <var>xmlfile</var>. One element per entry is added, after (<code>/After</code>, which is the default) or before (<code>/Before</code>) the current element, or replacing (<code>/Replace</code>) the current element. The argument <var>ename</var> is used as the element tag. If <code>/Data</code> is specified, the entry data is stored in the element's data section using the table's write format, otherwise (<code>/Empty</code> is the default), the entry data is stored as element attributes (use field names as attribute names, does not store empty fields, uses the write format) and the element data section is empty. In conjunction with <code>/Data</code>, the option <code>/Cdata</code> can be used to create CData sections instead of normal data sections. There is a severe performance hit (1.300%) if you use the <code>/Before</code> option since indexes have to be recalculated.
-<code>SET <var>xmlfile</var> ADDTABLE <var>table ename</var> [/After|Before|Replace] [/In|Out /Data|Empty /Cdata] [/Tagerrorsonly]</code>
+{|
+|-
-Add the entries of <var>table</var> as elements to <var>xmlfile</var>. One element per entry is added, after (/A = default) or before (/B) the current element, or replacing (/R) the current element. The argument <var>ename</var> is used as the element tag.. If /Data is specified the entry data is stored in the element's data section using the table's write format, otherwise (/Empty = default), the entry data is stored as element attributes (use field names as attribute names, does not store empty fields, uses the write format) and the element data section is empty. In conjunction with /Data, the option /Cdata can be used to create CData-sections instead of normal data sections. There is a severe performance hit (1300%) if you use the /Before option since indexes have to be recalculated.
+| <var>table</var>
+| A shell table with the entries to be added to the XML file. This parameter is mandatory.
-;<var>table</var>
+|-
+| <var>ename</var>
-:A shell table with the entries to be added to the XML file. This parameter is mandatory.
+| The string to be used as the created element's tag. This parameter is mandatory.
+|-
-;<var>ename</var>
+| <code>/After</code>, <code>/Before</code> or <code>/Replace</code>
+| Specify whether the new elements should be added before (<code>/Before</code>) or after (<code>/A</code>) the selected element or if they even should replace the selected element (<code>/Replace</code>).
-:The string to be used as the created element's tag. This parameter is mandatory.
+|-
+| <code>/In</code> or <code>Out</code>
-;<var>/After|Before|Replace</var>
+| If specified, <code>/In</code> navigates into the selected element before the new element is added. If specified, <code>/Out</code> navigates out of the selected element after the new element has been added.
+|-
-:Specify whether the new elements should be added before (/B) or after (/A) the selected element or replace the selected element (/R).
+| <code>/Data</code> or <code>/Empty</code>
+| If <code>/Data</code> is specified, then the entry is stored in the data section of the new element. Otherwise, the data is stored as attribute values.
-;<var>/In|Out</var>
+|-
+| <code>/Cdata</code>
-:If specified, /In navigates into the selected element before the new element is added. If specified, /Out navigates out of the selected element after the new element has been added.
+| Specify <code>/Cdata</code> if the data should be enclosed within a CData section.
+|-
-;<var>/Data|Empty</var>
+| <code>/TagErrorsOnly</code>
+| Specify if entries which cause errors should be tagged in the table but correct entries should be added. Otherwise, if one error occurs, no entries are added.
-:If /Data is specified, then the entry is stored in the data section of the new element. Otherwise, the data is stored as attribute values.
+|}
-;<var>/Cdata</var>
-:Specify /Cdata if the data should be enclosed within a CData section.
-;<var>/Tagerrorsonly</var>
-:Specify if entries which cause errors should be tagged in the table but correct entries should be added. Otherwise, if one error occurs, no entries are added.
+===XML: <code id="DELETEELEMENT">DELETEELEMENT</code>===
-===DELETEELEMENT===
+ SET <var>xmlfile</var> DELETEELEMENT [<var>ename</var>] [/Child]
-<code>SET <var>xmlfile</var> DELETEELEMENT [<var>ename</var>] [/Child]</code>
+Delete the selected element itself (no arguments) or delete all elements with the tag <var>ename</var> on the current level. If <code>/Child</code> is specified, the selected element's children are deleted, but not the selected element itself.
-Delete the selected element itself (no arguments) or delete all elements with the tag <var>ename</var> on the current level. If /Child is specified, the selected element's children are deleted, but not the selected element itself.
+'''Warning:''' This operation can take a very long time!
-Warning: This operation can take a very long time!<code>SET <var>xmlfile</var> DELETEELEMENT <var>table field</var> [/Resetpos /Child /All|Tagged]</code>
+ SET <var>xmlfile</var> DELETEELEMENT <var>table</var> <var>field</var> [/Resetpos /Child /All|Tagged]
 Delete all elements found at the positions stored in the column <var>field</var> of the table <var>table</var>.
-;<var>/Child</var>
+{|
+| <code>/Child</code>
-:If /Child is specified, the selected element's children are deleted, but not the selected element itself.
+| If <code>/Child</code> is specified, the selected element's children are deleted, but not the selected element itself.
+|-
-;<var>/Resetpos</var>
+| <code>/Resetpos</code>
+| The positions are deleted, but not the elements.
-:The positions are deleted, but not the elements.
+|-
+| <code>/All</code>
-;<var>/All</var>
+| All table entries are used. This is the default.
+|-
-:All table entries are used. This is the default.
+| <code>/Tagged</code>
+| Only tagged entries are used.
+|}
-;<var>/Tagged</var>
+===XML: <code id="EXTRACTFILE">EXTRACTFILE</code>===
-:Only tagged entries are used.
+ SET <var>xmlfile</var> EXTRACTFILE <var>xmlSubDoc</var> <var>posAttrName</var> [<var>tag<sub>N</sub></var> <var>recursive<sub>N</sub></var> &hellip; ]
-===EXTRACTFILE===
+Extract a selection of elements from a source xml file (<var>xmlfile</var>) into a target xml file (<var>xmlSubDoc</var>). The selection is dependent on the parameters <var>tag<sub>N</sub></var> and <var>recursive<sub>N</sub></var> and is independent of the selected element. The position of the extracted element in <var>xmlfile</var> is stored in the attribute <var>posAttrName</var> in the extracted element in <var>xmlSubDoc</var>. The original tree structure is retained. If no <var>tag<sub>N</sub></var>-names are given, then all positions in <var>xmlSubDoc</var> are removed from <var>xmlfile</var> and the contents of <var>xmlSubDoc</var> are deleted.
-<code>SET <var>xmlfile</var> EXTRACTFILE <var>xmlSubDoc posAttrName</var> [<var>tagN recursiveN</var> ...]</code>
+Note: the root element is always copied from <var>xmlfile</var> to <var>xmlSubDoc</var>. The pre-call contents (if any) are deleted from <var>xmlSubDoc</var>.
-Extract a selection of elements from a source xml file (<var>xmlfile</var>) into a target xml file (<var>xmlSubDoc</var>). The selection is dependent on the parameters <var>tagN</var> and <var>recursiveN</var> and is independent of the selected element. The position of the extracted element in <var>xmlfile</var> is stored in the attribute <var>posAttrName</var> in the extracted element in <var>xmlSubDoc</var>. The original tree structure is retained. If no <var>tagN</var>-names are given, then all positions in <var>xmlSubDoc</var> are removed from <var>xmlfile</var> and the contents of <var>xmlSubDoc</var> are deleted. Note: the root element is always copied from <var>xmlfile</var> to <var>xmlSubDoc</var>. The pre-call contents (if any) are deleted from <var>xmlSubDoc</var>.
+===XML: <code id="EXTRACTTABLE">EXTRACTTABLE</code>===
+There are a number of different flavours of the <code>EXTRACTTABLE</code> command. The flavour used depends on the use of the <code>/Mode</code> flag.
-===EXTRACTTABLE===
+ SET <var>xmlfile</var> EXTRACTTABLE <var>extTable</var> <var>posFld</var>|* <var>elemTag</var> <var>tagFld</var> <var>attr1Name</var> <var>attr1Fld</var> &hellip; [ /P /R /1|All /Y]
-<code>SET <var>xmlfile</var> EXTRACTTABLE <var>extTable posFld</var>|* <var>elemTag tagFld attr1Name attr1Fld</var> ... [ /P /R /1|All /Y]</code>
 Extract a selection of attribute values from elements with a specific tag on the current level into a table.
-;<var>extTable</var>
+{|
+|-
+| <var>extTable</var>
+| The id of an extended table item.
+|-
+| <var>posFld</var>
+| The name of the table field where element positions should be stored. If the option <code>/P</code> is specified, the position of the element's parent is save instead.
+|-
+| <var>elemTag</var>
+| The name of the element tag (e.g. "AFile" for <AFile> elements) or an asterisk for all elements.
+|-
+| <var>tagFld</var>
+| The name of the table field to store the extracted element tags.
+|-
+| <var>attr1Name</var>
+| The name of an attribute to extract.
+|-
+| <var>attr1Fld</var>
+| The name of the table field where the <var>attr1Name</var> attribute values should be stored.
+|-
+| <code>/Recursive</code>
+| If specified, the whole sub-tree is extracted.
+|-
+| <code>/Parent</code>
+| If specified, the element's parent's position is stored in the <var>posFld</var> column.
+|-
+| <code>/1</code> or <code>/All</code>
+| If <code>/1</code> is specified, elements are only extracted if ''any'' of the specified attributes are set. If <code>/All</code> is specified, elements are only extracted if ''all'' of the specified attributes are set. The default behaviour is to extract all elements irrespective of whether any attributes are set or not.
+|-
+| <code>/Y</code>
+| If specified, the <var>elemTag</var> argument is treated as a <code>DOCTYPE</code> class name and not only the elements, but also their derived classes are searched (e.g. if <var>elemTag</var> is <code>ASeg</code>, then all <code>APar</code>'s are searched too).
+|}
-:The id of an extended table item.
+If positions are stored (i.e. <var>posFld</var> is not set to <code>*</code>) the programmer is responsible for deleting the positions.
-;<var>posFld</var>
+ SET <var>xmlfile</var> EXTRACTTABLE <var>extTable</var> <var>elemTag<sub>1</sub></var> <var>nameFld<sub>1</sub></var> &hellip; /Mode=Attributes /Y /Recursive
-:The name of the table field where element positions should be stored. If the option /P is specified, the position of the element's parent is save instead.
+Saves a list of all the attributes found in the specified elements. The attributes of each element (<var>elemTag<sub>X</sub></var>) are stored in the associated table field <var>nameFld<sub>X</sub></var>.
-;<var>elemTag</var>
+{|
+| <code>/Mode=Attribute</code>
-:The name of the element tag (e.g. "AFile" for <AFile> elements) or an asterisk for all elements.
+| This is mandatory.
+|}
-;<var>tagFld</var>
-:The name of the table field to store the extracted element tags.
-;<var>attr1Name</var>
-:The name of an attribute to extract.
-;<var>attr1Fld</var>
-:The name of the table field where the <var>attr1Name</var> attribute values should be stored.
-;<var>/Recursive</var>
-:If specified, the whole sub-tree is extracted.
-;<var>/Parent</var>
-:If specified, the element's parent's position is stored in the <var>posFld</var> column.
-;<var>/1|All</var>
-:If /1 is specified, elements are only extracted if at least one of the specified attributes is set. If /All is specified, elements are only extracted if all of the specified attributes are set. The default behaviour is to extract all elements irrespective of whether any attributes are set or not.
-;<var>/Y</var>
-:If specified, the <var>elemTag</var> argument is treated as a <code>DOCTYPE</code> class name and not only the elements, but also their derived classes are searched (e.g. if <var>elemTag</var> is <code>ASeg</code>, then all <code>APar</code>'s are searched too).
-If positions are stored (i.e. <var>posFld</var> is not set to <code>*</code>) the programmer is responsible for deleting the positions.<code>SET <var>xmlfile</var> EXTRACTTABLE <var>extTable elemTag1 nameFld1</var> ... /Mode=Attributes /Y /Recursive</code>
-Saves a list of all the attributes found in the specified elements. Each elements (<var>elemTagX</var>) attributes are stored in the associated table field <var>nameFldX</var>.
-;<var>/Mode<code>=Attribute</code></var>
-:This is mandatory.
 See the command above for a description of the other parameters and options.
-<code>SET <var>xmlfile</var> EXTRACTTABLE <var>extTable posFld</var>|* <var>tagFld attr1Name attr1Fld</var> ... /Mode=Read [/All|Tagged]</code>
+ SET <var>xmlfile</var> EXTRACTTABLE <var>extTable</var> <var>posFld</var>|* <var>tagFld</var> <var>attr1Name</var> <var>attr1Fld</var> &hellip; /Mode=Read [/All|Tagged]
 Updates the attribute list already in the table <var>extTable</var>. No new elements are searched (i.e. the existing positions are used).
-;<var>/Mode=Read</var>
+{|
+| <code>/Mode=Read</code>
-:This is mandatory.
+| This is mandatory.
+|-
-;<var>/All|Tagged</var>
+| <code>/All</code> or <code>/Tagged</code>
+| If <code>/All</code> is specified, all table entries are used (this is the default). If <code>/Tagged</code> is specified, then only the tagged entries are used.
-: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 command above for a description of the other parameters and options.
-===ROOT===
+===XML: <code id="ROOT">ROOT</code>===
-<code>SET <var>xmlfile</var> ROOT [<var>*</var>|<var>tag</var>] [<var>aname avalue</var> ...] [/Delete]</code>
+ SET <var>xmlfile</var> ROOT [<var>*</var>|<var>tag</var>] [<var>aname<var> </var>avalue</var> &hellip; ] [/Delete]
-Name, rename or delete the root element tag, add, modify or delete the root element's attributes. An attribute is deleted if the value (<var>avalue</var>) passed is empty (''). If a doctype has been defined, the root's tag and attributes are validated and the function fails if the parameters are invalid. All required attributes which are not passed, are automatically set to their default values.
+Name, rename or delete the root element tag, add, modify or delete the root element's attributes. An attribute is deleted if the value (<var>avalue</var>) passed is empty (<code>''</code>>). If a doctype has been defined, the tag and attributes of the root element are validated and the function fails if the parameters are invalid. All required attributes which are not passed are automatically set to their default values.
-;<var>tag</var>
+{|
+|-
+| <var>tag</var>
+| root element tag (e.g. '<code>STxDataSet</code>'). If an asterisk is specified, the root element tag is left unmodifed.
+|-
+| <var>aname</var>
+| An XML attribute name. Used in combination with the <var>avalue</var> parameter, this can set or delete a root element attribute.
+|-
+| <var>avalue</var>
+| A value to assign to the previous <var>aname</var> attribute. You can delete an attribute if this parameter is an empty string (e.g. <code>$#file root * CH ''</code>)
+|-
+| <code>/Delete</code>
+| If specified, the root element and all of the contained content is removed. If used in combination with <var>tag</var>, this option deletes the document and then creates a new root element.
+|}
-:The root element tag (e.g. '<code>STxDataSet</code>'). If an asterisk is specified, the root element tag is left unmodifed.
+Using the <code>ROOT</code> command invalidates all saved positions!
-;<var>aname</var>
+===XML: <code id="SETATTRIBUTE">SETATTRIBUTE</code>===
-:An XML attribute name. Used in combination with the <var>avalue</var> parameter, this can set or delete a root element attribute.
+ SET <var>xmlfile</var> SETATTRIBUTE <var>aname</var> <var>avalue</var> &hellip; [/Parent]
-;<var>avalue</var>
+Set the attribute <var>aname</var> of the selected element to <var>avalue</var>. If <code>/Parent</code> is specified, the attributes of the parent element are modified instead of those of the selected element. Multiple attribute assignments (pairs of <code><var>aname</var> <var>avalue</var></code>) may be specified. An attribute is removed if an empty value is specified. If a doctype has been defined, the attributes are validated and the function fails if they are invalid.
-:A value to assign to the previous <var>aname</var> attribute. You can delete an attribute if this parameter is an empty string (e.g. <code>$#file root * CH ''</code>)
+Note: if the function fails, the pre-call state is not guaranteed (some attributes may have been set etc.).
+{|
-;<var>/Delete</var>
+|- <var>aname</var>
+| The name of the attribute to set.
-:If specified, the root element and all of the contained content is removed. If used in combination with <var>tag</var>, this option deletes the document and then creates a new root element.
+|-
+| <var>avalue</var>
-Using the ROOT command invalidates all saved positions!
+| The value to set the attribute to.
+|}
-===SETATTRIBUTE===
-<code>SET <var>xmlfile</var> SETATTRIBUTE <var>aname avalue</var> ... [/Parent]</code>
-Set the attribute <var>aname</var> of the selected element to <var>avalue</var>. If /Parent is specified, the attributes of the parent element are modified instead of those of the selected element. Multiple attribute assignments (pairs of <var>aname avalue</var>) may be specified. An attribute is removed if an empty value is specified. If a doctype has been defined, the attributes are validated and the function fails if they are invalid. Note: if the function fails, the pre-call state is not guaranteed (some attributes may have been set etc.).
-;<var>aname</var>
-:The name of the attribute to set.
-;<var>avalue</var>
-:The value to set the attribute to.
-<code>SET <var>xmlfile</var> SETATTRIBUTE <var>table</var> <var>field</var> <var>aname</var> <var>avalue</var> ...</code>
+ SET <var>xmlfile</var> SETATTRIBUTE <var>table</var> <var>field</var> <var>aname</var> <var>avalue</var> &hellip;
 The table <var>table</var> column <var>field</var> contains the positions of the elements who's attributes should be set.
-;<var>table</var>
+{|
+|-
-:The table item containing the positions of the elements where attribute should be set.
+| <var>table</var>
+| The table item containing the positions of the elements where attribute should be set.
-;<var>field</var>
+|-
+| <var>field</var>
-:The table item field where element positions are stored.
+| The table item field where element positions are stored.
+|-
-;<var>/Resetpos</var>
+| <code>/Resetpos</code>
+| All element positions will be deleted after use.
-:All element positions will be deleted after use.
+|-
+| <code>/All</code>
-;<var>/All</var>
+| All table entries will be used. This is the default.
+|-
-:All table entries will be used. This is the default.
+| <code>/Tagged</code>
+| Only tagged entries will be used.
-;<var>/Tagged</var>
+|-
+| <code>/Value</code>
-:Only tagged entries will be used.
+| The <var>avalue</var> arguments are attribute values.
+|-
-;<var>/Value</var>
+| <code>/Fieldid</code>
+| The <var>avalue</var> arguments are table field names which contain attribute values.
-:The <var>avalue</var> arguments are attribute values.
+|}
-;<var>/Fieldid</var>
-:The <var>avalue</var> arguments are table field names which contain attribute values.
+ SET <var>xmlfile</var> SETATTRIBUTE <var>tag</var> <var>aname</var> <var>avalue</var> &hellip; [/Y] [/Recursive]
-<code>SET <var>xmlfile</var> SETATTRIBUTE <var>tag</var> <var>aname</var> <var>avalue</var> ... [/Y] [/Recursive]</code>
 Set all the attributes of <var>tag</var> elements on the current level.
-;<var>tag</var>
+{|
+|-
+| <var>tag</var>
+| The tag identifying the elements to modify.
+|-
+| <code>/Y</code>
+| If the <code>/Y</code> option is used, the <var>tag</var> argument is used as a <code>DOCTYPE</code> class name, not an element tag. All derived classes are set too.
+|-
+| <code>/Recursive</code>
+| If specified, the command is carried out on the sub-tree as well.
+|}
-:The tag identifying the elements to modify.
+===XML: <code id="SORT">SORT</code>===
-;<var>/Y</var>
+ SET <var>xmlfile</var> SORT [<var>attrID<sub>0</sub></var> <var>dir<sub>0</sub></var> <var>attriID<sub>N</sub></var> <var>dir<sub>N</sub></var>] [/Delete]
-:If the /Y option is used, the <var>tag</var> argument is used as a <code>DOCTYPE</code> class name, not an element tag. All derived classes are set too.
+Sort the children of the selected element according to the given attributes and directions and set the element's <code>sort</code> attribute. Previous sort attributes are overwritten. Calling this function without parameters re-sorts using the existing attributes. Calling the function without parameters but with the <code>/Delete</code> option removes the sort attributes. This function only supports attributes defined in the doctype. Note that if one of the attributes is unique (as defined in the doctype definition), only this attribute will be used to sort.
-;<var>/Recursive</var>
+{|
+|-
-:If specified, the command is carried out on the sub-tree as well.
+| <var>attrId</var>
+| The name of an attribute defined in the doctype.
-===SORT===
+|-
+| <var>dir</var>
-<code>SET <var>xmlfile</var> SORT [<var>attrID0 dir0 attriIDN dirN</var>] [/Delete]</code>
+| The direction in which the elements should be sorted. The following values are allowed: <code>Ascending</code> and <code>Descending</code> (and any shorter version thereof, e.g. <code>Asc</code> or <code>Desc</code> or <code>a</code> or <code>d</code>) as well as <code>0</code> and <code>1</code>
+|-
-Sort the selected elements children according to the given attributes and directions and set the element's <code>sort</code> attribute. Previous sort attributes are overwritten. Calling this function without parameters resorts using the existing attributes. Calling the function without parameters and with the /Delete option removes the sort attributes. This function only supports attributes defined in the doctype. Note that if one of the attributes is unique (as defined in the doctype definition), only this attribute will be used to sort.
+| <code>/Delete</code>
+| If no parameters are passed, the existing sort attributes are deleted.
+|}
-;<var>attrId</var>
+The internal implementation works in the following way:
+;Unique Attributes: If one of the attributes passed to the <code>SORT</code> command is unique (as defined in the doctype), only this attribute is used for sorting. The elements are then sorted according to the direction and case is respected, if so defined in the doctype. All elements added to this level after sorting are added at the correct sorted position. Changing attributes of sorted elements also rearranges the sort order. If you have a large number of segments in an <code>AFile</code>, sorting according to a unique attribute is highly recommended, since the performance of the dataset validation is very bad for unsorted unique attributes. If you set the parent <code>sort</code> attribute by hand and want the sort to happen automatically, please set the <code>unsorted</code> attribute to <code>1</code>. Now the next time an attribute is changed, or an element is added, all elements will first be sorted.
+;Non-unique Attributes: If the sort attributes are not unique, multiple attributes can be used. Elements added after sorting are not inserted at the correct position; instead, a further attribute <code>unsorted</code> is set in the parent element. Changing attributes after sorting does not affect the sort order – the parent attribute <code>unsorted</code> is set.
+; Validation: The <code>VALIDATE</code> command checks for sort attributes and sorts the elements before validation. When closing {{STX}}, the DataSet is validated, and therefore all elements with sort attributes are sorted.
-:The name of an attribute defined in the doctype.
+==== Examples ====
-;<var>dir</var>
+ $#xmlfile SORT ID Asc
-:The direction in which the elements should be sorted. The following values are allowed: 'Ascending' or 'Descending' (or any shorter version thereof, e.g. 'Asc' or 'Desc' or 'a' or 'd'). or '0' or '1'
+The children of the selected element are sorted by their ID attribute in ascending order. The following command does the same by means of the SETATTRIBUTE command:
-;<var>/Delete</var>
+ SET $#xmlfile SETATTRIBUTE sort 'ID Asc' unsorted '1'
-:If no parameters are passed, the existing sort attributes are deleted.
+When the selected element of <code>$#xmlfile</code> is an AFile, all ASegs in this AFile will be sorted according to their ID. Sorting will happen automatically, either on modification/addition of an element or attribute to one of the ASegs, or on validation.
-The internal implementation works in the following way:Unique Attributes: If one of the attributes passed to the SORT command is unique (as defined in the doctype), only this attribute is used for sorting. The elements are sorted according to the direction and case is respected, if so defined in the doctype. All elements added to this level after sorting are added at the correct sorted position. Changing attributes of sorted elements also rearranges the sort order. If you have a large number of segments in an AFile, sorting according to a unique attribute is highly recommended, since the performance of the dataset validation is very slow for unsorted unique attributes. If you set the parent 'sort' attribute by hand and want the sort to happen automatically, please set the 'unsorted' attribute to '1'. The next time an attribute is changed, or an element is added, all elements will first be sorted.Non-unique Attributes: If the sort attributes are not unique, multiple attributes can be used. Elements added after sorting are not inserted at the correct position; instead, a further attribute 'unsorted' is set in the parent element. Changing attributes after sorting does not affect the sort order – the parent attribute 'unsorted' is set.Validation: the validate command checks for sort attributes and sorts the elements before validation. When closing {{STX}}, the DataSet is validated, and therefore all elements with sort attributes are sorted.<pre>
-SET $#xmlfile SORT ID Asc
-</pre>
-The children of the selected element are sorted by their ID attribute in ascending order. The following command does the same by means of the SETATTRIBUTE command.
-<pre>
-SET $#xmlfile SETATTRIBUTE sort 'ID Asc' unsorted '1'
-</pre>
-When <code>$#xmlfile</code>'s selected element is an AFile, all ASegs in this AFile will be sorted according to their ID. Sorting will happen automatically, either on modification/addition of an element or attribute to one of the ASegs, or on validation.
 ==XML Element Data Manipulation==
@@ Line 745: / Line 701: @@
 Note: You cannot store data in the data section of an element with children!
-===GETDATA===
+===XML: <code id="GETDATA">GETDATA</code>=== <!-- C.G. headings must be unique! -->
-<code>SET <var>xmlfile</var> GETDATA <var>varname</var></code>
+ SET <var>xmlfile</var> GETDATA <var>varname</var>
 Copy contents of XML data section into variable <var>varname</var>.
-<code>SET <var>xmlfile</var> GETDATA /Table <var>table</var> /Read</code>
+ SET <var>xmlfile</var> GETDATA /Table <var>table</var> /Read
-Empty table and copy contents of the XML data section into the table item <var>table</var>. This command loads data stored in the format generated by the command '<code>SET $#xmlfile SETDATA /T $#table</code>'.
+Empty table and copy contents of the XML data section into the table item <var>table</var>. This command loads data stored in the format generated by the command <code>SET $#xmlfile SETDATA /T $#table</code>.
-<code>SET <var>xmlfile</var> GETDATA /Table <var>table</var> [ <var>firstField nFields</var> ] /Numeric [/Vector]</code>
+ SET <var>xmlfile</var> GETDATA /Table <var>table</var> [ <var>firstField</var> <var>nFields</var> ] /Numeric [/Vector]
-Empty the table item <var>table</var> and copy the contents of the selected element's data section into the table's numeric fields. This command loads data stored in the format generated by the command <code>"SET $#xmlfile SETDATA /T/N $#table $#firstField $#nFields"</code>. This command uses the attributes <code>dim</code> and <code>vector</code> generated by the <code>SETDATA</code> command to ascertain the format of the data section. If the option /Vector is specified (see <code>SETDATA</code>), it overrides the corresponding <code>vector</code> attribute if it exists.
+Empty the table item <var>table</var> and copy the contents of the data section of the selected element into the numeric fields of the table. The <code>GETDATA</code> command loads data stored in the format set by the command <code>SET $#xmlfile SETDATA /T/N $#table $#firstField $#nFields</code>. Furthermore, it uses the attributes <code>dim</code> and <code>vector</code> set by the <code>SETDATA</code> command to ascertain the format of the data section. If the option <code>/Vector</code> is specified (see [[Programmer_Guide/Shell_Items/File/SET_FILE#SETDATA|<code>SETDATA</code>]] below), it overrides the corresponding <code>vector</code> attribute if it exists.
-===SETDATA===
+===XML: <code id="SETDATA">SETDATA</code>=== <!-- C.G. headings must be unique! -->
-<code>SET <var>xmlfile</var> SETDATA <var>string</var> [ /CData ]</code>
+ SET <var>xmlfile</var> SETDATA <var>string</var> [ /CData ]
-;<var>string</var>
+{|
+|-
+| <var>string</var>
+| The string to save in the element.
+|}
-:The string to save in the element.
+Set the data of the selected element to <var>string</var>. An empty string can be used to remove data (leading to an empty element). If the <var>string</var> contains characters which are reserved in the XML specification (e.g. &lt;, &gt;, &amp;), the option <code>/CData</code> must be used, which will create a <code>CData</code> section.
-Set the data of the selected element to <var>string</var>. An empty string can be used to remove data (-> empty element). If the <var>string</var> contains characters which are reserved in the XML specification (e.g. <, >, &), the option /CData must be used to create a CData section.
+ SET <var>xmlfile</var> SETDATA /Table <var>table</var> [ /CData ]
-<code>SET <var>xmlfile</var> SETDATA /Table <var>table</var> [ /CData ]</code>
+{|
+| <var>table</var>
+| The table containing the data to be stored in the element.
+|-
+| <code>/Table</code>
+| A mandatory option.
+|}
-;<var>table</var>
+Store the content of <var>table</var> in the data section of the selected element (note: this is different from <code>ADDTABLE</code>, which adds one element per entry). The write format of the table is always used (see [[Programmer_Guide/Shell_Items/Table/SET_TABLE#FORMAT|<code>SET table FORMAT</code>]]). If <var>table</var> contains characters which are reserved in the XML specification, the option <code>/CData</code> must be used.
-:The table containing the data to be stored in the element.
+ SET <var>xmlfile</var> SETDATA /Table <var>table</var> [ <var>firstField</var> <var>nfields</var> ] /Numeric [ /Vector ]
-;<var>/Table</var>
+{|
+|-
-:A mandatory option.
+| <var>firstField</var>
+| The first field to extract data from.
-Store the content of <var>table</var> in the data section of the selected element (note: this is different to <code>ADDTABLE</code>, which adds one element per entry). The table's write format is always used (see <code>SET table FORMAT</code>). If <var>table</var> contains characters which are reserved in the XML specification, the option /CData must be used.
+|-
+| <var>nFields</var>
-<code>SET <var>xmlfile</var> SETDATA /Table <var>table</var> [ <var>firstField nfields</var> ] /Numeric [ /Vector ]</code>
+| The number of consecutive fields to extract data from.
+|-
-;<var>firstField</var>
+| <code>/Numeric</code>
+| A mandatory option.
-:The first field to extract data from.
+|}
-;<var>nFields</var>
-:The number of consecutive fields to extract data from.
-;<var>/Numeric</var>
+Store the contents of <var>table</var> in the data section of the selected element. The <var>table</var> must be an [[Programmer_Guide/Shell_Items/Table/Introducing_Table_Items#Extended_Table|extended table]] and the selected fields must be numeric! The values are stored as decimal numbers. The data is stored row-by-row (if no additional option is supplied) or column-by-column (if option <code>/Vector</code> is given). The attribute <code>dim</code> is automatically added to the selected element with the values <code>"nRows nColumns"</code>. If the option <code>/Vector</code> is specified, the attribute <code>vector</code> is added with the value <code>"1"</code>.
-:A mandatory option.
-Store the contents of <var>table</var> in the data section of the selected element. The <var>table</var> must be an extended table and the selected fields must be numeric! The values are stored as decimal numbers. The data is stored row-by-row (no option) or column-by-column (option /Vector). The attribute <code>dim</code> is automatically added to the selected element with the values <code>"nRows nColumns"</code>. If the option /Vector is specified, the attribute <code>vector</code> is added with the value <code>"1"</code>.
 ==XML Element Positions==
-Element positions are unique strings which can be used like "pointers" to an element. The position of an element is saved with the command "<code>#posvar := POSITION $#file</code>" (see the command <code>POSITION</code>).
+Element positions are unique ID strings which can be used like pointers or references to an element. The position of an element is saved with the command "<code><var>#posvar</var> := POSITION $<var>#file</var></code>" (see the command [[Programmer_Guide/Command_Reference/POSITION|<code>POSITION</code>]]).
-===POSITION===
-<code>SET xmlfile POSITION [ <var>parameters</var> ... ] [ /S ]</code>
-All <code>POSITION</code> commands can take the /S option.
+===XML: <code id="POSITION">POSITION</code>===
-;<var>/S</var>
+ SET <var>xmlfile</var> POSITION [ <var>parameters</var> &hellip; ] [ [[Programmer_Guide/Command_Reference_Options/Silent|/Silent]] ]
-:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.
+All <code>POSITION</code> commands support the [[Programmer_Guide/Command_Reference_Options/Silent|<code>/Silent</code> option]].
-<code>SET <var>xmlfile</var> POSITION <var>pos</var> /Restore [ /S ]</code>
+ SET <var>xmlfile</var> POSITION <var>pos</var> /Restore [ /Silent ]
 Select the element at position <var>pos</var> and delete the position.
-<code>SET <var>xmlfile</var> POSITION <var>pos</var> /Goto [ /S ]</code>
+ SET <var>xmlfile</var> POSITION <var>pos</var> /Goto [ /Silent ]
 Select the element at position <var>pos</var> but do not delete the position.
-<code>SET <var>xmlfile</var> POSITION [<var>pos</var>|<var>*</var>] /Delete [/Children] [ /S ]</code>
+ SET <var>xmlfile</var> POSITION [<var>pos</var>|*] /Delete [/Children] [ /Silent ]
-Delete the position identified by <var>pos</var>. If <var>pos</var> is empty or an asterisk, then all saved positions for the selected element are deleted. If the option /Children is used, this (position) deletion is carried out recursively.
+Delete the position identified by <var>pos</var>. If <var>pos</var> is empty or an asterisk, then ''all'' saved positions for the selected element are deleted. If the option <code>/Children</code> is used, this position deletion is carried out recursively.
-<code>SET <var>xmlfile</var> POSITION <var>pos1</var> [<var>pos2</var>] /Equal [ /S ]</code>
+ SET <var>xmlfile</var> POSITION <var>pos<sub>1</sub></var> [<var>pos<sub>2</sub></var>] /Equal [ /Silent ]
-Tests if the two positions <var>pos1</var> and <var>pos2</var> reference the same element (<code>RC=0</code> for same element, <code>RC=1</code> for different elements). If only one position (<var>pos1</var>) is passed, this position is compared with that of the selected element.
+Tests if the two positions <var>pos<sub>1</sub></var> and <var>pos<sub>2</sub></var> reference the same element (<code>RC=0</code> for same element, <code>RC=1</code> for different elements). If only one position (<var>pos<sub>1</sub></var>) is passed, this position is compared with that of the selected element.
 ==XML Load & Save==
-===LOAD===
+=== XML: <code>LOAD</code>=== <!-- C.G. headings must be unique! -->
+ SET <var>xmlfile</var> LOAD [<var>path</var>]
-<code>SET <var>xmlfile</var> LOAD [<var>path</var>]</code>
+Load the document from the last selected or specified path and select the root element (previous content/position information is lost). If a <var>path</var> is specified, data are loaded from path and it is stored for later use, otherwise the stored path is used. The current content and all position and state settings are cleared before loading.
-Load the document from the last selected or specified path and select the root element (previous content/position information is lost). If a <var>path</var> is specified, data are loaded from path and it is stored for later use, otherwise the stored path is used. The current content and all position and state settings are cleared before loading
+The function sets <var>RC</var> to <samp>0</samp> on success.
-===SAVE===
+=== XML: SAVE=== <!-- C.G. headings must be unique! -->
-<code>SET <var>xmlfile</var> SAVE [<var>path</var>]</code>
+ SET <var>xmlfile</var> SAVE [<var>path</var>]
-Store the document in the last selected or specified <var>path</var>. If <var>path</var> is specified, it is also stored for later use.
+Store (i.e., save to disk) the document in the supplied <var>path</var> or, if none is supplied, in the last selected path. If <var>path</var> is specified, it is also stored for later use.
-==XML Navigation Searching==
+==XML Navigation And Searching==
-The following general navigation options can be supplied with any navigation, search and data processing command:
+The following general navigation options can be supplied with any of the navigation, search and data processing command:
-*/In step into the selected element: set the selected element to the parent element and its first child to the selected element; this option is applied after successful execution of the navigation or manipulation function
+* <code>/In</code> step into the selected element: set the selected element to the parent element and its first child to the selected element; this option is applied after successful execution of the navigation or manipulation function
-*/Out step out of the parent: set the element containing the current parent to the new parent and the current parent to the selected element; this option is applied before the function is executed
+* <code>/Out</code> step out of the parent: set the element containing the current parent to the new parent and the current parent to the selected element; this option is applied before the function is executed
-*/First|Last|Next set position to the first|last element of current section or continue navigation|search ; this option is applied before the function is executed (after /Out option)
+* <code>/First</code>, <code>/Last</code> and <code>/Next</code> set the position to the first or last element of the current section (<code>/First</code> or <code>/Last</code>) or continue navigation/search (<code>/Next</code>); these options are applied ''before'' the respective function is executed (but ''after'' the <code>/Out</code> option).
-*/nodetype selects the type of the node to be found; the types /Element, /Processinginstruction, /Comment and /Doctype are supported
+* <code>/nodetype</code> selects the type of the node to be found; the types /Element, /Processinginstruction, /Comment and /Doctype are supported
-===Find===
+===XML: <code id="Find_2">FIND</code>===
-The <code>SET <var>xmlfile</var> FIND</code> command searches in an XML file for one, or more, occurences of a certain node. There are two variants of using the command:
+ SET <var>xmlfile</var> FIND
+The <code>FIND</code> command searches an XML file for one, or more, occurences of a certain node. There are two variants of using the command:
 * consecutively searching for the first (<code>SET <var>xmlfile</var> FIND /First</code>), and any further occurence (<code>SET <var>xmlfile</var> FIND /Next</code>); or
-* searching for all occurrences in a single operation, returning them in an {{STX}} table (SET <var>xmlfile</var> FIND <var>tableitem</var>&hellip;)
+* searching for ''all'' occurrences in a single operation, returning them in an {{STX}} table (<code>SET <var>xmlfile</var> FIND <var>tableitem</var>&hellip;</code>)
-;Consecutive FIND operations:
+==== Consecutive <code>FIND</code> operations ====
- SET <var>xmlfile</var> FIND <var>*</var>|<var>tag</var> [<var>cexpr</var> [<var>loper</var> &hellip;]] [/In|Out /First|Next] [/Element|Processinginstruction|Doctype] [/Y]
-Search for a node of the selected type (/E = default, /P, /D, see <code>SET file GOTO</code>) with the tag <var>*</var>|<var>tag</var> on the level of the selected element. For nodes of type ''element'' the arguments <var>cexpr</var> (conditional expression for attribute values, see the [[#cexpr Conditions|table below]]) and <var>loper</var> (logical operator) are formatted and processed similarly to the <code>SET table</code> <code>FIND</code> function (e.g. <code>attributename:<=:1000</code> or <code>attributename:=I:a*.0*</code> and so on). Use the option <code>/First</code> (default) to begin search at the first element in the section, and <code>/Next</code> to start with the element following the selected element. If the node is found, it is selected, otherwise the selection remains unaffected. If the option /Y is specified, then <var>tag</var> is treated as a <code>DOCTYPE</code> class name, rather than an XML element tag (this means derived types are also recognised).
+ SET <var>xmlfile</var> FIND <var>*</var>|<var>tag</var> [ [[#cexpr|<var>cexpr</var>]] [ [[Programmer_Guide/Concepts/Conditional_Expressions#loper|<var>loper</var>]] &hellip;]] [/In|Out /First|Next] [/Element|Processinginstruction|Doctype] [/Y]
+Search for a node of the selected type (<code>/Element</code> which is the default, <code>/Processinginstruction</code>, <code>/Doctype</code>, see [[Programmer_Guide/Shell_Items/File/SET_FILE#GOTO|<code>SET file GOTO</code>)]] with the tag <var>*</var> or <var>tag</var> on the level of the selected element. For nodes of type ''element'' the arguments <var>cexpr</var> (conditional expression for attribute values, see the [[#cexpr|table below]] and <var>loper</var> ([[Conditional_Expressions#loper|logical operator]]<!-- WTF? -->) are formatted and processed similarly to the [[Programmer_Guide/Shell_Items/Table/SET_TABLE#FIND|<code>SET table</code> <code>FIND</code>]] function (e.g. <code>attributename:<=:1000</code> or <code>attributename:=I:a*.0*</code>). Use the option <code>/First</code> (default) to begin search at the first element in the section, and <code>/Next</code> to start with the element following the selected element. If the node is found, it is selected, otherwise the selection remains unaffected. If the option <code>/Y</code> is specified, then <var>tag</var> is treated as a <code>DOCTYPE</code> class name, rather than an XML element tag (this means derived types are also recognised).
 The shell variable <code>RC</code> is set to the integer <code>7</code> if the command was syntactically correct, but no element was found. The shell variable <code>RC</code> is set to the integer value <code>0</code> if an element corresponding to the search criteria was found.
-Find and delete the first element on the current level with the attribute <code>ID</code> with a value of <code>3</code>.
+===== Example =====
+Find and delete the first element on the current level that has an <code>ID</code> attribute with a value of <code>3</code>:
   $#f find * 'ID:==:3' /First
-  if '$rc' == '0' $#f deleteelement
+  if '$rc' == 0 $#f deleteelement
+==== Returning all results in a table ====
+ SET <var>xmlfile</var> FIND <var>postable</var> <var>posfield</var> <var>tag</var> [ [[#cexpr|<var>cexpr</var>]] [ [[Programmer_Guide/Concepts/Conditional_Expressions#loper|<var>loper</var>]] [[#cexpr|<var>cexpr</var>]] &hellip;]&hellip;] [/Recursive /Y]
-;Returning all results in a table:
+Like the above <code>FIND</code> commands, except that the command does not return when it finds the first match, rather it saves the position of ''all'' matching elements in ''one'' field (<var>posfield</var>) of the specified table (<var>postable</var>). If the option <code>/Recursive</code> is specified, the whole sub-tree is searched. If the option <code>/Y</code> is specified, the <var>tag</var> string is treated as a <code>DOCTYPE</code> class name rather than an element tag, and all derived classes are searched.
- SET <var>xmlfile</var> FIND <var>postable</var> <var>posfield</var> <var>tag</var> [<var>cexpr</var> [<var>loper</var> <var>cexpr</var>&hellip;]&hellip;] [/Recursive /Y]
-Like the above <code>FIND</code> commands, except that the command does not return when it finds the first match, rather it saves the position of all matching elements in one field (<var>posfield</var>) of the specified table (<var>postable</var>). If the option /R is specified, the whole sub-tree is searched. If the option /Y is specified, the <var>tag</var> string is treated as a <code>DOCTYPE</code> class name rather than an element tag, and all derived classes are searched.
+{|
+|-
+| <var>posTable</var>
+| The extended table where to store element positions.
+|-
+| <var>posField</var>
+| The extended table field in which to store element positions.
+|}
-;<var>posTable</var>
+For all other parameters, please see the [[#Consecutive FIND operations|consecutive variant of the <code>FIND</code>]] command (above), and the [[#cexpr|table of <code>cexpr</code> expressions]] (below).
-:The extended table where to store element positions.
-;<var>posField</var>
-:The extended table field in which to store element positions.
-For all other parameters, please see the [[#Consecutive FIND operations|consecutive variant of the <code>FIND</code>]] command (above), and the [[#cexpr Conditions|table of <code>cexpr</code> expressions]] (below).
+===== Example =====
   // find all elements with a specific numerical attribute value
   $#f find $#t $#tField $#elem '$#elemAttr:==:$#elemattrvalue' /Recursive
-;Conditions:
+==== <span id="Conditions"><span id="cexpr">Find Conditions</span></span> ====
 {|
 |-
@@ Line 924: / Line 891: @@
 |}
+===XML: <code id="GOTO">GOTO</code>===
-===GOTO===
+ SET <var>xmlfile</var> GOTO [<var>epath</var>] [/First|Next|Last] [/In|Out] [/Element|Comment|Processinginstruction|Doctype] [/Reset]
-<code>SET <var>xmlfile</var> GOTO [<var>epath</var>] [/First|Next|Last] [/In|Out] [/Element|Comment|Processinginstruction|Doctype] [/Reset]</code>
+Go to the first (<code>/First</code>, last (<code>/Last</code>) or next (<code>/Next</code>) element. If <var>epath</var> is specified, go to the first (<code>/First</code>, last (<code>/Last</code>) or next (<code>/Next</code>) element matching <var>epath</var>.
-Go to the first, last or next element. If epath is specified, go to the first, last or next element matching <var>epath</var>.
+You can specify the type of node to navigate to with the options <code>/Element</code>, <code>/Comment</code>, <code>/Processinginstruction</code> and <code>/Doctype</code>, respectively. If only the node type option is used (without argument and other options), the first node of the respective type in the document is located.
-You can specify the type of node to navigate to with the options /E|C|P|D. If only the node type option is used (without argument and other options) the first node of this type in the document is found.
+The options <code>/First</code>, <code>/Next</code> and <code>/Last</code> only work with <var>epath</var> if <var>epath</var> does not contain slashes, i.e. if it specifies an element tag without an actual path (e.g. "<code>elemtag</code>"). For multi-level <var>epaths</var> like '<code>*/elemtag</code>' or '<code>/root/elemtag/elemtag</code>', the search finds the ''first'' element every time, and neither of <code>/First</code>, <code>/Next</code> and <code>/Last</code> should be supplied.
-The options /F|N|L only work for <var>epath</var> if <var>epath</var> is one level (e.g. '<code>elemtag</code>'). For <var>epaths</var> like '<code>*/elemtag</code>' or '<code>/root/elemtag/elemtag</code>', the search finds the first element every time.
+{|
+|-
-;<var>epath</var>
+| <var>epath</var>
+| The path of the element to go to. The normal format of <var>epath</var> is "<code>elemtag</code>". If you want to go to an element on a deeper level, the format is '<code>*/elemtag</code>'. The format of <var>epath</var> is absolute if it starts with the forward slash (e.g. '<code>/rootelem/firstelem</code>'). To ensure that <var>epath</var> is correctly interpreted, always enclose it in single quotation marks. XML is case sensitive, so <var>epath</var> must match exactly (wildcards are not supported). If no options are given, the current position is reset to the first child element of the root element.
-:The path of the element to go to. The normal format of <var>epath</var> is '<code>elemtag</code>'. If you want to go to an element on a deeper level, the format is '<code>*/elemtag</code>'. The format of <var>epath</var> is absolute if it starts with the forward slash (e.g. '<code>/rootelem/firstelem</code>'). To ensure that <var>epath</var> is correctly interpreted, enclose it in inverted commas. XML is case sensitive, so <var>epath</var> must match exactly (wildcards are not supported). If no options are given, the current position is reset to the first child element of the root element.
+|-
+| <code>/First</code>, <code>/Next</code> or <code>/Last</code>
-;<var>/First|Next|Last</var>
+| Determines whether to navigate to the first, last or next element. The default is <code>/Next</code>.
+|-
-:Determines whether to navigate to the first, last or next element. The default is /Next.
+| <code>/E</code> || Navigate to a data element node (e.g. <code>&lt;elemtag&gt;</code>)
+|-
-;<var>/Element|Comment|Processinginstruction|Doctype</var>
+| <code>/C</code> || Navigate to an XML comment (e.g. <code>&lt;!-- comment --&gt;</code>). The argument <var>epath</var> is ignored.
+|-
-:If specified, the type of node to navigate to can chosen.
+| <code>/P</code> || Navigate to an XML processing instruction (e.g. <code>&lt;?pinst &hellip;?&gt;</code>). The argument <var>epath</var> is used as the tag name of the processing instruction node.
+|-
-:/E - a data element node (e.g. <elemtag>)
+| <code>/Doctype</code> || Navigate to a document type (e.g. <code>&lt;!DOCTYPE typename &hellip;&gt;</code>). The argument <var>epath</var> is used for the name of the document type. The default is <code>/Element</code>.
+|-
-:/C - an XML commend (e.g. <!-- comment -->). The argument <var>epath</var> is ignored.
+| <code>/Reset</code>
+| Reset the element selection. This means that no element is selected and a GOTO command with the option /Next will navigate to the first element.
-:/P - an XML processing instruction (e.g. <?pinst ...?>). The argument <var>epath</var> is used as the tag name of the processing instruction node.
+|-
+| <code>/In</code>
-:/Doctype - a document type(e.g. <!DOCTYPE typename ...>). The argument <var>epath</var> is used for the name of the document type.
+| step into the selected element: set the selected element to the parent element and its first child to the selected element; this option is applied after successful execution of the navigation or manipulation function
+|-
+| <code>/Out</code>
+| step out of the parent: set the element containing the current parent to the new parent and the current parent to the selected element; this option is applied before the function is executed
+|}
-:The default is <code>/Element</code>.
+Note that you can get yourself into difficulties if you use multiple options, e.g <code>/i /f</code>. Although you may feel inclined to think you are going to navigate ''in'' and go to the ''first'' element there, you will actually go to the first element and then navigate in.
-;<var>/Reset</var>
+You can use the [[Programmer Guide/Shell Items/File/FILE Item Attributes|file item attribute]] <code>!XCHILDREN</code> to determine if an element has children or not.
-:Reset the element selection. This means that no element is selected and a GOTO command with the option /Next will navigate to the first element.
+<var>RC</var> is set to <samp>0</samp> if the element is found and a value greater than 0 if not.
-Note that you can get yourself into difficulties if you use multiple options, e.g /i /f. Although you may think, you are going to navigate in and go to the first element, you will actually go to the first element and then navigate in. You can use the [[Programmer Guide/Shell Items/File/FILE Item Attributes|file item attribute]] <code>!XCHILDS</code> to determine if an element has children or not.<pre>
+==== Example ====
-// go to the root element <STxColorPalette>
+ // go to the root element <STxColorPalette>
-$#xmlfile goto '/STxColorPalette'
+ $#xmlfile goto '/STxColorPalette'
-</pre>

Programmer Guide/Shell Items/File/SET FILE: Difference between revisions

Latest revision as of 09:55, 24 June 2019

Contents

Binary File Commands

Binary Files: LIST

Binary Files: LOAD

Binary Files: SAVE

Finding Files on Disk

Finding Files: FIND

Finding Files: NEXT

Status File Commands

Status Files: STATUS

Status Files: DELETE

Status Files: RENAME and COPY

Text and Section File I/O

Text Files: LIST

Text Files: LOAD

Text Files: SAVE

Text Files: SYNC

Locking / Unlocking File Items

XML Doctype

DOCTYPE ELEMENT

DOCTYPE CHILD

DOCTYPE ROOT

DOCTYPE NAME

DOCTYPE CLOSE

VALIDATE

XML Element and Attribute Manipulation

XML: ADDELEMENT

XML: ADDFILE

XML: DOCTYPE ATTRIBUTE

XML: ADDNODE

XML: ADDTABLE

XML: DELETEELEMENT

XML: EXTRACTFILE

XML: EXTRACTTABLE

XML: ROOT

XML: SETATTRIBUTE

XML: SORT

Examples

XML Element Data Manipulation

XML: GETDATA

XML: SETDATA

XML Element Positions

XML: POSITION

XML Load & Save

XML: LOAD

XML: SAVE

XML Navigation And Searching

XML: FIND

Consecutive FIND operations

Example

Returning all results in a table

Example

Find Conditions

XML: GOTO

Example

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Tools

Binary Files: `LIST`

Binary Files: `LOAD`

Binary Files: `SAVE`

Finding Files: `FIND`

Finding Files: `NEXT`

Status Files: `STATUS`

Status Files: `DELETE`

Status Files: `RENAME` and `COPY`

Text Files: `LIST`

Text Files: `LOAD`

Text Files: `SAVE`

Text Files: `SYNC`

`DOCTYPE ELEMENT`

`DOCTYPE CHILD`

`DOCTYPE ROOT`

`DOCTYPE NAME`

`DOCTYPE CLOSE`

`VALIDATE`

XML: `ADDELEMENT`

XML: `ADDFILE`

XML: `DOCTYPE ATTRIBUTE`

XML: `ADDNODE`

XML: `ADDTABLE`

XML: `DELETEELEMENT`

XML: `EXTRACTFILE`

XML: `EXTRACTTABLE`

XML: `ROOT`

XML: `SETATTRIBUTE`

XML: `SORT`

XML: `GETDATA`

XML: `SETDATA`

XML: `POSITION`

XML: `LOAD`

XML: `FIND`

Consecutive `FIND` operations

XML: `GOTO`