SET FILE

From STX Wiki
Jump to navigationJump to search
File Item
INTRODUCING NEW SET ATTRIBUTES EXAMPLES

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 ℵ0)

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

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

Saves a list of all the attributes found in the specified elements. The attributes of each element (elemTagX) 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 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 [attrID0 dir0 attriIDN dirN] [/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 pos1 [pos2] /Equal [ /Silent ]

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

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'
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Shell_Items/File/SET_FILE&oldid=10435"

Navigation menu

Personal tools