Programmer Guide/Shell Items/File/SET FILE - Revision history

Jw: /* Text and Section File I/O */

2019-06-24T08:55:09Z

Text and Section File I/O

← Older revision		Revision as of 10:55, 24 June 2019
Line 111:		Line 111:
	==Text and Section File I/O==		==Text and Section File I/O==

	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 … /Text</code>]] and [[Programmer_Guide/Shell_Items/File/NEW_FILE#Section_Files\|<code>NEW FILE … /Section</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 … /Text</code>]] and [[Programmer_Guide/Shell_Items/File/NEW_FILE#Section_Files\|<code>NEW FILE … /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.

	SET <var>file</var> <var>cmd</var> <var>table</var> [<var>type</var> <var>name</var>]		SET <var>file</var> <var>cmd</var> <var>table</var> [<var>type</var> <var>name</var>]

Jw: /* VALIDATE */

2018-11-29T08:57:09Z

VALIDATE

← Older revision		Revision as of 10:57, 29 November 2018
Line 330:		Line 330:
	SET <var>xmlfile</var> VALIDATE <var>errorTable</var>\|<var>*</var> [<var>testdoc</var> /Insert] [/Recursive] [/Position /Children /Attributes] [/Showposition]		SET <var>xmlfile</var> VALIDATE <var>errorTable</var>\|<var>*</var> [<var>testdoc</var> /Insert] [/Recursive] [/Position /Children /Attributes] [/Showposition]

	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 ~~options~~ <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;).		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;).

	{\|		{\|

Jw: /* VALIDATE */

2018-11-29T08:56:32Z

VALIDATE

← Older revision		Revision as of 10:56, 29 November 2018
Line 330:		Line 330:
	SET <var>xmlfile</var> VALIDATE <var>errorTable</var>\|<var>*</var> [<var>testdoc</var> /Insert] [/Recursive] [/Position /Children /Attributes] [/Showposition]		SET <var>xmlfile</var> VALIDATE <var>errorTable</var>\|<var>*</var> [<var>testdoc</var> /Insert] [/Recursive] [/Position /Children /Attributes] [/Showposition]

	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 0. 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 options <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;).		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 options <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;).

	{\|		{\|

Jw: /* VALIDATE */

2018-11-29T08:56:15Z

VALIDATE

← Older revision		Revision as of 10:56, 29 November 2018
Line 330:		Line 330:
	SET <var>xmlfile</var> VALIDATE <var>errorTable</var>\|<var>*</var> [<var>testdoc</var> /Insert] [/Recursive] [/Position /Children /Attributes] [/Showposition]		SET <var>xmlfile</var> VALIDATE <var>errorTable</var>\|<var>*</var> [<var>testdoc</var> /Insert] [/Recursive] [/Position /Children /Attributes] [/Showposition]

	Validate the <var>xmlfile</var>'s selected element using the defined doctype. If all tests are passed, or if no doctype is defined, 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 (<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 options <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;).		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 0. 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 options <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;).

	{\|		{\|

Jw: /* XML: ADDFILE */

2018-11-29T08:15:48Z

XML: ADDFILE

← Older revision		Revision as of 10:15, 29 November 2018
Line 386:		Line 386:
	* 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 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><?xml?></code> and <code><!DOCTYPE></code> entries) are not copied.		* Note that if the root element of the source document is added, the nodes on that level (e.g. the <code><?xml?></code> and <code><!DOCTYPE></code> entries) are not copied.

			This function sets <var>RC</var> to <samp>0</samp> on success.

	===XML: <code id="DOCTYPE_ATTRIBUTE">DOCTYPE ATTRIBUTE</code>===		===XML: <code id="DOCTYPE_ATTRIBUTE">DOCTYPE ATTRIBUTE</code>===

Jw at 08:14, 29 November 2018

2018-11-29T08:14:55Z

← Older revision		Revision as of 10:14, 29 November 2018
Line 785:		Line 785:
	SET <var>xmlfile</var> LOAD [<var>path</var>]		SET <var>xmlfile</var> LOAD [<var>path</var>]

	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 'RC' to 0 on success.		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.

	=== XML: SAVE=== <!-- C.G. headings must be unique! -->		=== XML: SAVE=== <!-- C.G. headings must be unique! -->

Jw: /* XML: SORT */

2018-10-30T08:14:58Z

XML: SORT

← Older revision		Revision as of 10:14, 30 October 2018
Line 681:		Line 681:

	The internal implementation works in the following way:		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.		;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.		;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.		; 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.

Jw: /* Locking / Unlocking File Items */

2018-08-14T09:37:22Z

Locking / Unlocking File Items

← Older revision		Revision as of 11:37, 14 August 2018
Line 226:		Line 226:
	SET <var>file</var> LOCK		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.		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.


	SET <var>file</var> LOCK <var>timeout</var>		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.		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.


	SET <var>file</var> UNLOCK		SET <var>file</var> UNLOCK

Jw: /* Locking / Unlocking File Items */

2018-08-14T09:37:15Z

Locking / Unlocking File Items

← Older revision		Revision as of 11:37, 14 August 2018
Line 222:		Line 222:
	==Locking / Unlocking File Items==		==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 own thread.		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 <var>file</var> LOCK		SET <var>file</var> LOCK

Jw at 09:18, 14 August 2018

2018-08-14T09:18:14Z

← Older revision		Revision as of 11:18, 14 August 2018
Line 175:		Line 175:
	\| 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 [[Programmer_Guide/Command_Reference_Options/Silent\|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 [[Programmer_Guide/Shell_Items/Table/SET_TABLE#Formatting_table_fields\|Formatting_table_fields]].

	See <code>load_a_file_into_a_table.sts</code> in the script examples directory for a working example.		See <code>load_a_file_into_a_table.sts</code> in the script examples directory for a working example.