Programmer Guide/Shell Items/File/SET FILE

Binary File Commands

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

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.

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,…) or -1 to append a section (the latter is the default).
/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

FIND

SET file FIND search [ /F|D ]

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.

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

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.

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.

RENAME and COPY

SET file RENAME|COPY path newpath [ [[Programmer_Guide/Command_Reference_Options/Silent|/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.

COPY

SET fileItem COPY /Z /E|D sourceFile [ targetFile|* [ password|* ]

Copy a source to a target file encrypting/decrypting it in the process.

/Encrypt or /Decrypt

encrypt the file, or decrypt it

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.

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.

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

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.

SYNC

SET file SYNC

Write section file from memory to disk

Locking / Unlocking File Items

LOCK

SET file LOCK

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

SET file TRYLOCK [ timeout ] [ /S ]

Try to lock the file item file. If no timeout is specified, TRYLOCK returns immediately. If the caller already *holds* the lock, TRYLOCK will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting.

timeout

If specified, TRYLOCK will try to get a lock once per millisecond until it is either successful, or timeout milliseconds have elapsed.

/S

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

Return Codes:

0 - an unlocked file has been successfully locked.

348 - Error: if the file item could not be locked due to it being locked by someone else.

349 - Error: if the file item could not be locked due to it being locked by the caller.

Example:

"SET $#file TRYLOCK 5000" 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.

The TRYLOCK command is intended for safe multithreading without race conditions occurring

UNLOCK

SET file UNLOCK

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 "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 required and 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 (= all DOCTYPE commands before DOCTYPE CLOSE) must consist of at least one element definition and the root and name assignment.

The application 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|yes}
vchildren	show children in dialogs {no|yes}(5)
vattributes	yes|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 (>= 0 or *=0)
maxoccur	maximum number of occurrences (>=minoccur or * for infinite)

DOCTYPE ROOT

SET xmlfile DOCTYPE ROOT tag

Assign the type tag of the root element. The element type must already be 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 no doctype is defined, it returns true. If all tests are passed, it returns true. 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 (/R). The position (/P), attributes (/A) and the occurrence of children (/C) 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 options /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 /S modifies any error strings, prefixing the string with a position id (e.g. 'P#54 ASeg has invalid attributes').

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.

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 = default) the selected element of xmlfile or it replaces (/Replace) the selected element. Attribute assignments (aname avalue) can be specified to set element attributes.

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 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|Last are then performed. After the element is added, the /In option is carried out.

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 = 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 (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).

source

The source XML file item to be added.

/After|Before|Replace

Insert the source file after or before the selected element, or replace the selected element.

/In|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's been added.

/Children

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!

/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|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.

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	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
type	params
INTEGER	minimum maximum
NUMBER	minimum maximum
STRING	respectcase unique
VALUELIST	value1 value2 ...

|- |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) |- |value1, value2 |possible values of a valuelist attribute |}

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|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.

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 (/A = default) or before (/B) the current element, or replacing (/R) 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 = 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.

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|Replace

Specify whether the new elements should be added before (/B) or after (/A) the selected element or replace the selected element (/R).

/In|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|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.

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.

EXTRACTFILE

SET xmlfile EXTRACTFILE xmlSubDoc posAttrName [tagN recursiveN ...]

Extract a selection of elements from a source xml file (xmlfile) into a target xml file (xmlSubDoc). The selection is dependent on the parameters tagN and recursiveN 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 tagN-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.

EXTRACTTABLE

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|All

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.

/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 elemTag1 nameFld1 ... /Mode=Attributes /Y /Recursive

Saves a list of all the attributes found in the specified elements. Each elements (elemTagX) attributes are stored in the associated table field nameFldX.

/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|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.

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 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.

tag

The 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!

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.).

aname

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.

SORT

SET xmlfile SORT [attrID0 dir0 attriIDN dirN] [/Delete]

Sort the selected elements children according to the given attributes and directions and set the element's sort 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.

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' or 'Descending' (or any shorter version thereof, e.g. 'Asc' or 'Desc' or 'a' or 'd'). or '0' or '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 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.

SET $#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 $#xmlfile'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

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

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 selected element's data section into the table's numeric fields. This command loads data stored in the format generated by the command "SET $#xmlfile SETDATA /T/N $#table $#firstField $#nFields". This command uses the attributes dim and vector generated by the SETDATA command to ascertain the format of the data section. If the option /Vector is specified (see SETDATA), it overrides the corresponding vector attribute if it exists.

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 (-> empty element). If the string contains characters which are reserved in the XML specification (e.g. <, >, &), the option /CData must be used to 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 to ADDTABLE, which adds one element per entry). The table's write format 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 (no option) or column-by-column (option /Vector). 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 strings which can be used like "pointers" to an element. The position of an element is saved with the command "#posvar := POSITION $#file" (see the command POSITION).

POSITION

SET xmlfile POSITION [ parameters ... ] [ /S ]

All POSITION commands can take the /S option.

/S

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

SET xmlfile POSITION pos /Restore [ /S ]

Select the element at position pos and delete the position.

SET xmlfile POSITION pos /Goto [ /S ]

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

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

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 pos1 [pos2] /Equal [ /S ]

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

XML Load & Save

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

SAVE

SET xmlfile SAVE [path]

Store the document in the last selected or specified path. If path is specified, it is also stored for later use.

XML Navigation Searching

The following general navigation options can be supplied with any 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|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)
• /nodetype selects the type of the node to be found; the types /Element, /Processinginstruction, /Comment and /Doctype are supported

Find

The SET xmlfile FIND command searches in 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 (/E = default, /P, /D, see SET file GOTO) with the tag *|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* and so on). 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.

Find and delete the first element on the current level with the attribute ID 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 /R 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).

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

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

GOTO

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

Go to the first, last or next element. If epath is specified, go to the first, last or next element matching epath.

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 /F|N|L only work for epath if epath is one level (e.g. 'elemtag'). For epaths like '*/elemtag' or '/root/elemtag/elemtag', the search finds the first element every time.

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, enclose it in inverted commas. 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|Last

Determines whether to navigate to the first, last or next element. The default is /Next.

/Element|Comment|Processinginstruction|Doctype

If specified, the type of node to navigate to can chosen.

/E - a data element node (e.g. <elemtag>)

/C - an XML commend (e.g. ). The argument epath is ignored.

/P - an XML processing instruction (e.g. <?pinst ...?>). The argument epath is used as the tag name of the processing instruction node.

/Doctype - 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.

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 file item attribute !XCHILDS to determine if an element has children or not.

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