Programmer Guide/Macro Library/BXMLDoc: Difference between revisions

From STX Wiki
Jump to navigationJump to search
No edit summary
 
(34 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}__NOTOC__
{{DISPLAYTITLE:{{SUBPAGENAME}} - General XML Document}}
This class implements a general XML document.
:'''File''': BXMLDOC.STX, linked to library STX.LIB
:'''Parent class''': [[Programmer Guide/Macro Library/COBJ|CObj]], '''Derived classes''': [[Programmer Guide/Macro Library/BSTXIni|BSTXIni]], [[Programmer Guide/Macro Library/BDataSet|BDataSet]]


;Parent class: CObj
This class implements a general xml-document. It is mainly used to implement the common part of the two main {{STx}} documents: the project <code>BDataSet</code> and the workspace <code>BSTXIni</code>.
;Derived classes: [[Programmer Guide/Class Library/BSTXIni|BSTXIni]], [[Programmer Guide/Class Library/BDataset|BDataset]]
 
;Content: [[#Construction]], [[#Access control]], [[#Query attributes]], [[#File handling]], [[#Global items]], [[#Element manipulation]]


==Construction==
==Construction==
Line 38: Line 36:
Because an BXMLDoc instance can be used by more than one shell, there must be a mechanism to control the access to the instance and its data content.
Because an BXMLDoc instance can be used by more than one shell, there must be a mechanism to control the access to the instance and its data content.


 
====Attach====
;<code><var>bxmldoc</var> Attach [ <var>iref</var> ]</code>:  
;<code><var>bxmldoc</var> Attach [ <var>iref</var> ]</code>:
:;<var>iref</var>: Element reference or xml-position.
:;<var>iref</var>: Element reference or xml-position.
;Result: name of file-item of the document
;Result: name of file-item of the document
Line 45: Line 43:
:This function should be called any time before a shell uses a shared XML document. If a shell issues more than one <code>Attach</code> function call, it must use the same number of <code>Detach</code> calls to unlock the XML document.
:This function should be called any time before a shell uses a shared XML document. If a shell issues more than one <code>Attach</code> function call, it must use the same number of <code>Detach</code> calls to unlock the XML document.


 
====Detach====
;<code><var>bxmldoc</var> Detach</code>:  
;<code><var>bxmldoc</var> Detach</code>:  
;Result: 1 if the xml-file-item was changed while it was locked and 0 if not. The return value is also 0 if the xml-file-item was not unlocked by the <code>Detach</code> function.
;Result: 1 if the xml-file-item was changed while it was locked and 0 if not. The return value is also 0 if the xml-file-item was not unlocked by the <code>Detach</code> function.
Line 51: Line 49:


==Query attributes==
==Query attributes==
====GetFileItem====
;<code><var>bxmldoc</var> GetFileItem</code>: Get the XML file item of the instance. The file should only be accessed directly if the XML document is locked to the shell (see [[#Access control]]). The use of the file item may be necessary to perform attribute access, element data access or special browse / search functions.
;<code><var>bxmldoc</var> GetFileItem</code>: Get the XML file item of the instance. The file should only be accessed directly if the XML document is locked to the shell (see [[#Access control]]). The use of the file item may be necessary to perform attribute access, element data access or special browse / search functions.
;Result: the xml-file-item
;Result: the xml-file-item


 
====GetDocType====
;<code><var>bxmldoc</var> GetDocType</code>: Retrieve the name of the doctype if a doctype is defined for the root element of the XML file.
;<code><var>bxmldoc</var> GetDocType</code>: Retrieve the name of the doctype if a doctype is defined for the root element of the XML file.
;Result: name of XML doctype or empty string (if no doctype is defined for the document)
;Result: name of XML doctype or empty string (if no doctype is defined for the document)


 
====GetPath====
;<code><var>bxmldoc</var> GetPath</code>: Retrieve the name of the XML file as stored on the hard drive. The result is empty if no file is associated with the document (this means the file exists in memory and was never loaded or saved). The function sets the <code>&path</code> member variable.
;<code><var>bxmldoc</var> GetPath</code>: Retrieve the name of the XML file as stored on the hard drive. The result is empty if no file is associated with the document (this means the file exists in memory and was never loaded or saved). The function sets the <code>&path</code> member variable.
;Result: the path of the the xml-file-item
;Result: the path of the the xml-file-item


==File handling==
==File handling==
====Load====
;<code><var>bxmldoc</var> Load [ <var>path</var> ]</code>: Load the content of the file <var>path</var> into the xml-file-item of the document. If <var>path</var> is not specified, the current path is used (see <code>GetPath</code>).
;<code><var>bxmldoc</var> Load [ <var>path</var> ]</code>: Load the content of the file <var>path</var> into the xml-file-item of the document. If <var>path</var> is not specified, the current path is used (see <code>GetPath</code>).
;Result: 0 for success or errorcode
;Result: 0 for success or errorcode


 
====Save====
;<code><var>bxmldoc</var> Save [ <var>path</var> ]</code>: Save the xml-file-item of the document to the file <var>path</var>. If <var>path</var> is not specified, the current path is used (see <code>GetPath</code>).
;<code><var>bxmldoc</var> Save [ <var>path</var> ]</code>: Save the xml-file-item of the document to the file <var>path</var>. If <var>path</var> is not specified, the current path is used (see <code>GetPath</code>).
;Result: 0 for success or errorcode
;Result: 0 for success or errorcode


 
====Close====
;<code><var>bxmldoc</var> Close [ <var>save</var>=0 [; <var>path</var> ] ]</code>: Close the xml-file-item and delete the instance <var>bxmldoc</var>. If the argument <var>save</var> is set to <code>1<code>, the document is saved before it is deletec (using the function call <code><var>bxmldoc</var> Save [ <var>path</var> ]</code>).
;<code><var>bxmldoc</var> Close [ <var>save</var>=0 [; <var>path</var> ] ]</code>: Close the xml-file-item and delete the instance <var>bxmldoc</var>. If the argument <var>save</var> is set to <code>1</code>, the document is saved before it is deletec (using the function call <code><var>bxmldoc</var> Save [ <var>path</var> ]</code>).
;Result: 0 for success or errorcode (returned from <code>Save</code>).
;Result: 0 for success or errorcode (returned from <code>Save</code>).
;Note: The instance <var>bxmldoc</var> is deleted, even if the function returns an errorcode.
;Note: The instance <var>bxmldoc</var> is deleted, even if the function returns an errorcode.
Line 78: Line 78:
This class implements some members to share items between shells. This feature is used f.i. by the application <code>Viewer1</code> to implement the '''signal copy-paste''' functions and by some other applications.
This class implements some members to share items between shells. This feature is used f.i. by the application <code>Viewer1</code> to implement the '''signal copy-paste''' functions and by some other applications.


 
====AddGlobalItem====
;<code><var>bxmldoc</var> AddGlobalItem <var>id</var> ; <var>item</var></code>:  
;<code><var>bxmldoc</var> AddGlobalItem <var>id</var> ; <var>item</var></code>:  
:;<var>id</var>: The global id-string to use for <var>item</var>.
:;<var>id</var>: The global id-string to use for <var>item</var>.
Line 85: Line 85:
;Description: Add a shell item to the global item list. All items in the global item list can be linked by other shells, which have created a linked (shared) instance of this XML document. All types of items except displays, graphs and dialogs can be used.
;Description: Add a shell item to the global item list. All items in the global item list can be linked by other shells, which have created a linked (shared) instance of this XML document. All types of items except displays, graphs and dialogs can be used.


 
====AttachGlobalItem====
;<code><var>bxmldoc</var> AttachGlobalItem <var>id</var> [; <var>lock</var>=0 ]</code>:
;<code><var>bxmldoc</var> AttachGlobalItem <var>id</var> [; <var>lock</var>=0 ]</code>:
:;<var>id</var>: The id-string of the global-item.
:;<var>id</var>: The id-string of the global-item.
Line 92: Line 92:
;Description: Creates a [[Programmer_Guide/Shell_Items#References_to_shell_items|linked instance (reference)]] of the global item with the specified id. If lock is set to 1 the linked instance is locked to the calling shell.
;Description: Creates a [[Programmer_Guide/Shell_Items#References_to_shell_items|linked instance (reference)]] of the global item with the specified id. If lock is set to 1 the linked instance is locked to the calling shell.


 
====DetachGlobalItem====
;<code><var>bxmldoc</var> DetachGlobalItem <var>item</var> [; <var>unlock</var>=0 ]</code>:
;<code><var>bxmldoc</var> DetachGlobalItem <var>item</var> [; <var>unlock</var>=0 ]</code>:
:;<var>item</var>: A shell-item linked to a global-item.
:;<var>item</var>: A shell-item linked to a global-item.
Line 99: Line 99:
;Description: Deletes a linked item. If unlock is set to 1 the linked item is unlocked before it is removed.
;Description: Deletes a linked item. If unlock is set to 1 the linked item is unlocked before it is removed.


 
====DeleteGlobalItem====
;<code><var>bxmldoc</var> AttachGlobalItem <var>id</var> [; <var>delete</var>=0 ]</code>:
;<code><var>bxmldoc</var> DeleteGlobalItem <var>id</var> [; <var>delete</var>=0 ]</code>:
:;<var>id</var>: The id-string of the global-item.
:;<var>id</var>: The id-string of the global-item.
:;<var>delete</var>: If set to <code>1</code> the shell-item is deleted.
:;<var>delete</var>: If set to <code>1</code> the shell-item is deleted.
Line 107: Line 107:


==Element manipulation==
==Element manipulation==
====AddElement====
;<code><var>bxmldoc</var> AddElement <var>tag</var> ; <var>where</var> ; <var>goto</var> ; <var>attr</var>=<var>value</var> ; ...</code>:
;<code><var>bxmldoc</var> AddElement <var>tag</var> ; <var>where</var> ; <var>goto</var> ; <var>attr</var>=<var>value</var> ; ...</code>:
:;<var>tag</var>: The element tag.
:;<var>tag</var>: The element tag.
Line 115: Line 116:
;Description: Add a new element with the specified tag to the XML document. The element is added on the same level as the current element (<var>where</var>=<code>CURRENT</code>) or as child element (<var>where</var>=<code>CHILD</code>) of the current element. The attribute assignment <var>attr</var>=<var>value</var> are used to initialize the new elements attributes. If the function returns <code>0</code> the new element is created and the position is changed according to the argument <var>goto</var>, otherwise the document content and the current element position are not changed. To assign the attributes to the element the function call <code><var>bxmldoc</var> SetElement * ; <var>attr</var>=<var>value</var> ; ...</code> is used.
;Description: Add a new element with the specified tag to the XML document. The element is added on the same level as the current element (<var>where</var>=<code>CURRENT</code>) or as child element (<var>where</var>=<code>CHILD</code>) of the current element. The attribute assignment <var>attr</var>=<var>value</var> are used to initialize the new elements attributes. If the function returns <code>0</code> the new element is created and the position is changed according to the argument <var>goto</var>, otherwise the document content and the current element position are not changed. To assign the attributes to the element the function call <code><var>bxmldoc</var> SetElement * ; <var>attr</var>=<var>value</var> ; ...</code> is used.


 
====SetElement====
;<code><var>bxmldoc</var> SetElement <var>pos</var> ; <var>attrarg</var> ; ... </code>:
;<code><var>bxmldoc</var> SetElement <var>pos</var> ; <var>attrarg</var> ; ... </code>:
:;<var>pos</var>: The xml-position or element reference of the element to be changed. The value <code>*</code> :;attrarg: Defines the name and the value of the attribute(s) to be set.  
:;<var>pos</var>: The xml-position or element reference of the element to be changed. The value <code>*</code> :;attrarg: Defines the name and the value of the attribute(s) to be set.  
Line 121: Line 122:
::;<var>attrtab</var>: The name of a simple-table containing one attribute setting <code> <var>aname</var> = <var>avalue</var> </code> per entry. This table gets deleted after processing!
::;<var>attrtab</var>: The name of a simple-table containing one attribute setting <code> <var>aname</var> = <var>avalue</var> </code> per entry. This table gets deleted after processing!
;Result: 0 for success or errorcode.
;Result: 0 for success or errorcode.
;Description: Set the attributes of a specific element. The current position is not changed by this function. An error is returned, if no element is found at the specified position <var>pos</var>, or an attribute assignment fails. If an error is returned, some attributes of the element may be changed! To remove an attribute, an empty attribute value can be used (<code> <var>aname</var><code>=; </code> ).
;Description: Set the attributes of a specific element. The current position is not changed by this function. An error is returned, if no element is found at the specified position <var>pos</var>, or an attribute assignment fails. If an error is returned, some attributes of the element may be changed! To remove an attribute, an empty attribute value can be used (<code> <var>aname</var>=; </code>).
 


====GetElement====
;<code><var>bxmldoc</var> GetElement <var>pos</var> ; <var>info</var> ; aname1 ; ... </code>:
;<code><var>bxmldoc</var> GetElement <var>pos</var> ; <var>info</var> ; aname1 ; ... </code>:
:;<var>pos</var>: The xml-position or element reference of the element.The value <code>*</code> can be used for the element at the current position.
:;<var>pos</var>: The xml-position or element reference of the element.The value <code>*</code> can be used for the element at the current position.
:;<var>info</var>:
:;<var>info</var>:
::;<code>0<code>: get attribute values &rarr; result = <var>avalue1; ...</var>
::{|class="einrahmen"
::;<code>1<code>: get element tag and attribute values &rarr; result = <var>tag; avalue1; ...</var>
|<code>0</code> ||get attribute values ||result = <var>avalue1; ...</var>
::;<code>2<code>: get element tag, number of children and attribute values &rarr; (result = <var>tag; nchildren; avalue1; ...</var>
|-
|<code>1</code> ||get element tag and attribute values ||:result = <var>tag; avalue1; ...</var>
|-
|<code>2</code> ||get element tag, number of children and attribute values ||result = <var>tag; nchildren; avalue1; ...</var>
|}
:;<var>aname1</var>, ...: list of attribute names  
:;<var>aname1</var>, ...: list of attribute names  
;Result: empty string (element not found) or a string containing selected informations (see argument <var>info</var>)
;Result: empty string (element not found) or a string containing selected informations (see argument <var>info</var>)
;Description: Retrieve general informations about the specified element and/or element attribute values. The current element position is not changed by this function.
;Description: Retrieve general informations about the specified element and/or element attribute values. The current element position is not changed by this function.


 
====DeleteElement====
;<code><var>bxmldoc</var> DeleteElement <var>pos</var></code>:
;<code><var>bxmldoc</var> DeleteElement <var>pos</var></code>:
:;<var>pos</var>: The xml-position or element reference of the element.The value <code>*</code> can be used for the element at the current position.
:;<var>pos</var>: The xml-position or element reference of the element.The value <code>*</code> can be used for the element at the current position.
Line 141: Line 146:


==Data manipulation==
==Data manipulation==
====GetDataType====
;<code><var>bxmldoc</var> GetDataType [ <var>tag</var> ]</code>:
;<code><var>bxmldoc</var> GetDataType [ <var>tag</var> ]</code>:
:;<var>tag</var>: The element tag to be tested; if not specified or set to <code>*</code> the tag of the current element is used.
:;<var>tag</var>: The element tag to be tested; if not specified or set to <code>*</code> the tag of the current element is used.
Line 146: Line 152:
;Description: Returns type of date stored in elements with the specified tag. This function is used by <code>LoadData</code> and <code>SaveData</code> to retrieve data type information. In the current doctype-version only the types <code>TABLE</code> and '<code>XTABLE tabledef</code>' are supported.
;Description: Returns type of date stored in elements with the specified tag. This function is used by <code>LoadData</code> and <code>SaveData</code> to retrieve data type information. In the current doctype-version only the types <code>TABLE</code> and '<code>XTABLE tabledef</code>' are supported.


 
====CreateXTable====
;<code><var>bxmldoc</var> CreateXTable <var>typedef</var> [ <var>fname1</var> ... ]</code>:
;<code><var>bxmldoc</var> CreateXTable <var>typedef</var> [ <var>fname1</var> ... ]</code>:
:;<var>typedef</var>: The name (ID) of the <code>XTableTypeDef</code> element.
:;<var>typedef</var>: The name (ID) of the <code>XTableTypeDef</code> element.
Line 154: Line 160:
;Note: A <var>typedef</var> for an extended table is defined in an xml element with the tag <code>XTableTypeDef</code> with the attribute <code>ID="<var>typedef</var>"</code>. This element must be defined in the definition-section of the {{STX}} configuration file or on level of the current element.  
;Note: A <var>typedef</var> for an extended table is defined in an xml element with the tag <code>XTableTypeDef</code> with the attribute <code>ID="<var>typedef</var>"</code>. This element must be defined in the definition-section of the {{STX}} configuration file or on level of the current element.  


 
====LoadData====
;<code><var>bxmldoc</var> LoadData</code>:
;<code><var>bxmldoc</var> LoadData</code>:
;Result: The name of the shell-item (table) containing the loaded data or an empty string.
;Result: The name of the shell-item (table) containing the loaded data or an empty string.
Line 162: Line 168:
...
...
$bstxini attach
$bstxini attach
$bstxini selectiref '/Definitions/DataSet/$#argv'
$bstxini selectiref '/Definitions/DataSet/Methods'
if '$result' == 0 #data := $bstxini loaddata
if '$result' == 0 #data := $bstxini loaddata
$bstxini detach
$bstxini detach
Line 168: Line 174:
</pre>
</pre>


 
====SaveData====
;<code><var>bxmldoc</var> SaveData <var>item</var> [ ; <var>del</var>=0 ]</code>:
;<code><var>bxmldoc</var> SaveData <var>item</var> [ ; <var>del</var>=0 ]</code>:
:;<var>item</var>: Shell-item (table) containing the data to be saved.
:;<var>item</var>: Shell-item (table) containing the data to be saved.
Line 177: Line 183:


==IRef functions==
==IRef functions==
* This group of functions was originally developed, to deal with elements of type '''Set''' with the special unique id attribute '''ID'''. This implementation was modified, because the attribute '''ID''' is now used as a unique identifier for elements of any type.
* This group of functions was originally developed, to deal with unique references to elements of type '''Set''' with the special unique id attribute '''ID'''. This implementation was modified, because the attribute '''ID''' is now used as a unique identifier for elements of any type.
* A string in the format '''/id1/id2/.../idn''' is called '''IRef''' (for "(unique) Internal REFerence").  
* A string in the format ''' /''id1''/''id2''/.../''idn'' ''' is called '''IRef''' (for "(unique) Internal REFerence"). This string is interpreted as follows:
** ''id1'' is the unique element id (value of attribute '''ID''') on the root-level
** ''id2'' is the unique element id inside the element selected by ''id1''
** and so on


====SelectIRef====
{{/SelectIRef}}


====FormatIRef====
;<code><var>bxmldoc</var> FormatIRef [ <var>pos</var>=* ]</code>
:;<var>pos</var>: The XML element position or <code>*</code> for the current element.
;Result: A reference (IRef) to the selected element or an empty string.
;Description:Generates the internal XML reference string for the specified element at position <var>pos</var>. This string can only be created if all elements in the path except the root element have an ID attribute.
;see also: commands [[Programmer_Guide/Command_Reference/IREF|IREF]] and [[Programmer_Guide/Command_Reference/POSITION|POSITION]]


====UniqueID====
;<code><var>bxmldoc</var> UniqueID [ <var>pos</var>=* ; <var>id</var>=* ; <var>ext</var>=0 ; <var>start</var>=-1 ; <var>digits</var>=0 ]</code>
:;<var>pos</var>: The position/reference of the parent element (<code>*</code> = current element)
:;<var>id</var>: The fixed part of the id-string. If an asterisk is specified, the string "Auto" is used.
:;<var>ext</var>: Use the counter in the id-extension (<code>yes</code> or <code>1</code>) or append the counter directly to the id-string (<code>no</code> or <code>0</code>).
;<var>start</var>: The counter start value. Use <code>-1</code> to test <var>id</var> without the counter suffix: if <var>id</var> is unique it is returned without any modifications.
;<var>digits</var>: The number of digits. Use a value outside the range <code>2..9</code> to disable zero padding. If e.g. <var>digits</var> equals 3, the generated counter values will be <code>000</code>, <code>001</code>, <code>002</code>, etc.
;Result: A unique id string (unique on the selected level) or an empty string on failure.
;Description: Generate a unique id for the current level or inside the specified parent element. If <var>id</var> is unique, then <var>id</var> is returned. Otherwise, the counter is appended to <var>id</var> in the requested format.


===AddSetElement===
=="Set" functions==
* This group of functions was originally developed to deal with elements of type '''Set''' with the special unique id attribute '''ID'''. This implementation was modified, because the attribute '''ID''' is now used as a unique identifier for elements of any type.


Create a new element with specified tag and id in the set selected by <var>ref</var>. If the specified set does not exist, it will be created. If a set must be created, for each set element the tag <code>SET</code> is used by default, but it is possible to specify another tag in the argument <code>ref</code> with the format: <code>/setid/.../settag:setid/.../</code>. If the element is created, the new element is selected, otherwise the position is not changed.
===ListSetElements===
<code><var>bxmldoc</var> ListSetElements [ <var>table</var>=* ; <var>iref</var>=* ]</code>
:;<var>table</var>: simple table-item to store result; if <code>*</code> is used a new table is created
:;<var>iref</var>: reference of the set-element containing the elements to be listed; use <code>*</code> for the current level
;Result: the table-item containing the result (list of id's) or an empty string
;Description: Lists all element id's on the current level (<var>iref</var>=*) or inside the specified set-element. If a table-item is passed, it is emptied before the id list is stored, otherwise a new table is created.


=====Usage:=====
===FindSetElement===
<code><var>bxmldoc</var> FindSetElement [ <var>tag</var>=* ; <var>id</var>=* ; <var>iref</var>=* ]</code>
:;<var>tag</var>: element tag; use <code>*</code> for all elements
:;<var>id</var>: value of ID attribute; wildcards are possible
:;<var>iref</var>: reference of the set-element to be searched; use <code>*</code> for the current level
;Result: 0 if the element was found and 1 if not
;Description: Find the (first element) with the specified <var>tag</var> (* = search all element tags) and <var>id</var>. For the matching of tag and id a case-sensitive comparison is used! If no <var>iref</var> is specified, the current level is searched from the beginning, otherwise the search is performed inside the specified set.


<code><var>inst</var> AddSetElement <var>tag</var> ; <var>id</var> ; <var>ref</var></code>
===AddSetElement===
<code><var>bxmldoc</var> AddSetElement [ <var>tag</var> ; <var>id</var> ; <var>iref</var>=* ]</code>
:;<var>tag</var>: element tag
:;<var>id</var>: element id (value of ID attribute)
:;<var>iref</var>: reference of the set-element where the element should be created; use <code>*</code> for the current level
;Result: 0 if the element was selected/created and 1 if not
;Description: Create a new element with specified tag and id in the set selected by <var>iref</var>. If the specified set does not exist, it will be created. If a set must be created, for each set element the tag <code>SET</code> is used by default, but it is possible to specify another tag in the argument <code>ref</code> with the format: <code>/setid/.../settag:setid/.../</code>. If the element is created, the new element is selected, otherwise the position is not changed. If the element exists already, it is selected but not changed.


=====Parameters:=====
===LoadSetElement===
 
<code><var>bxmldoc</var> LoadSetElement [ <var>tag</var>=* ; <var>id</var>=* ; <var>iref</var>=* ]</code>
;<var>tag</var>
;Result: The loaded data object (table-item, value returned from <code>LoadData</code>) or an empty string.
 
:Description: This function uses the call <code><var>bxmldoc</var> FindSetElement <var>tag</var>;<var>id</var>;<var>iref</var></code> to select the element and the call <code><var>bxmldoc</var> LoadData</var></code> to load the content of the selected element. If element selection or loading data failes (error), the file position is not changed, otherwise (success) the loaded element is selected.
:The element tag. E.g. '<code>ASet</code>'.
 
;<var>id</var>
 
:The element id. E.g. <code><ASet ID='myId'></code>
 
;<var>ref</var>
 
:The reference of a set, or an asterisk for the current level.
 
=====Result:=====
 
0 for success or non-zero error code.
 
===AFUN function arguments===
 
=====usage:=====
 
{|
|-
|function
|name of member function to be called
|-
|arguments
|arguments for the member function
|}
 
=====result:=====
 
result returned from member function call
 
=====description:=====
 
This function attaches the XML document to the calling shell, executes the member function call 'function arguments' and detaches the XML document.
 
 
 
===CLOSE [save ; path]===
 
=====usage:=====
 
{|
|-
|save
|save before close (0=no, 1=yes; def.=0)
|-
|path
|path of output XML disk file
|}
 
=====result:=====
 
0 for success or non<nowiki>-</nowiki>zero error code
 
=====description:=====
 
Close the XML document. If save equals 1 the function call 'SAVE path' is used to save the document. The result of this function is the result of the save call, or 0 if the document was not saved. When this function returns, the XML document is closed and the document instance is deleted! (regardless of the return code).
 
 
===DeleteElement===
 
=====Usage:=====
 
<code><var>inst</var> DeleteElement <var>ref</var>|*</code>
 
=====Parameters:=====
 
;<var>ref</var>
 
:The element IRef or an asterisk for the current position.
 
=====Result:=====
 
<code>0</code> for success or non-zero error code
 
=====Description:=====
 
 
 
===DELETESETELEMENT tag ; id ; ref===
 
=====usage:=====
 
{|
|-
|tag
|element tag
|-
|Id
|element id
|-
|ref
|reference of set or * for current level
|}
 
=====result:=====
 
0 for success or non<nowiki>-</nowiki>zero error code
 
=====description:=====
 
Delete the set element specified by tag, id and ref.
 
===DESTRUCT===
 
=====result:=====
 
none
 
=====description:=====
 
Deinitialize and close the XML document. The destructor do not save the XML document to the XML disk file. If the object is a shared XML document (created with LINK) only the link is removed, but the other shares stay active. A shared XML file is closed when the last share is removed.
 
 
===DialogSelectElement===
 
Extracts a sub-document using the function <code>ExtractSubDoc</code> and displays the sub-document tree in a dialog where the user can select one or more elements (depending on <var>selmode</var>). Depending on <var>outmode</var>, either the position/s or the internal reference/s of the selected element/s is/are returned. If <var>outmode</var> is set to <code>POSITION</code> the user must cleanup the positions when the element processing is finished.
 
=====Usage:=====
 
<code><var>inst</var> DialogSelectElement <var>title</var> ; <var>selmode</var> ; <var>outmode</var> ; <var>tag1</var> ; <var>sub1</var> ; <var>tagX</var> ; <var>subX</var> ; ...</code>
 
=====Parameters:=====


;<var>title</var>
===SaveSetElement===
<code><var>bxmldoc</var> SaveSetElement [ <var>item</var> ; <var>del</var>=0 ; <var>tag</var>=* ; <var>id</var>=* ; <var>iref</var>=* ]</code>
;Result: 0 if the data item was saved successful and 1 otherwise
:Description: This function uses the call <code><var>bxmldoc</var> AddSetElement <var>tag</var>;<var>id</var>;<var>iref</var></code> to select or create the element and the call <code><var>bxmldoc</var> SaveData</var></code> to save the item into the element. If element selection or save operation failes (error), the file position is not changed, otherwise (success) the created/updated element is selected.


:The dialog window caption.
===DeleteSetElement===
<code><var>bxmldoc</var> DeleteSetElement [ <var>tag</var>=* ; <var>id</var>=* ; <var>iref</var>=* ]</code>
;Result: 0 if the element was deleted and 1 otherwise
:Description: This function calls <code><var>bxmldoc</var> FindSetElement <var>tag</var>;<var>id</var>;<var>iref</var></code> to select an element and than deletes the selected element.


;<var>selmode</var>
==Misc==


:The selection mode {<code>SINGLE</code>|<code>MULTIMPLE</code>}.
====SavePos====
<code><var>bxmldoc</var> SavePos [ <var>delpos</var>=* ]</code>
;Result: current xml position id or empty string if position can not be saved (no element selected)
;Description: Returns the xml position id of the currently selected element. If the xmp position id <var>delpos</var> is not equal <code>*</code>, this position is closed (reset).
;See Also: [[Programmer_Guide/Command_Reference/POSITION|POSITION]]


;<var>outmode</var>
====ResetPos====
<code><var>bxmldoc</var> ResetPos <var>pos</var>=* [ ; * ; <var>delemem</var>=0 ] </code>
;Result: always 0
;Description: Restore the the xml position id <var>pos</var>. If <var>delelem</var> equals 1 the element at the restored position is deleted.


:The output mode {<code>POSITION</code>|<code>IREF</code>}


;<var>tagX, subX</var>
<code><var>bxmldoc</var> ResetPos <var>table</var>=* [ ; <var>row</var>=* ; <var>delemem</var>=0 ; <var>deltable</var>=0 ] </code>
;Result: always 0
;Description: Restore all xml positions stored in <var>table[*,row]</var>. If <var>table</var> is a simple table, the argument <var>row</var> is ignored.
::* If <var>delelem</var> equals <code>1</code> the elements at the restored positions are deleted
::* If <var>deltable</var> equals <code>1</code> the <var>table</var> is deleted
::* This function can be used to reset positions returned by [[Programmer_Guide/Shell_Items/File/SET_FILE#Find_2|FIND]] or [[Programmer_Guide/Shell_Items/File/SET_FILE#EXTRACTTABLE|EXTRACTTABLE]] commands.


:The tag name and subtree scan flag, are passed to function <code>ExtractSubDoc</code>. Note that
====ExtractSubDoc====
;<code><var>bxmldoc</var> ExtractSubDoc <var>file</var> ; <var>posattr</var> ; <var>tag1</var> ; <var>sub1</var> ; <var>tag2</var> ; <var>sub2</var> ; ...</code>:
:;<var>file</var>: The target XML file item for extracted elements.
:;<var>posattr</var>: The name of element attribute for positions of original elements.
:;<var>tagX</var>: The element tags to be extracted.
:;<var>subX</var>: Flag determining if child elements of <var>tagX</var> should be scanned scan too (yes=<code>1</code>, no=<code>0</code>).
;Result: none (void), <var>file</var> contains extracted elemenents
;Description: Extract the elements with the specified tags from the document and copy them into the specified target <var>file</var>. The original tree structure is retained. The content of an element with <var>tagX</var> is only scanned if the corresponding <var>subX</var> argument is set to <code>1</code> (or <code>yes</code>). The element data are not extracted. If <var>posattr</var> is not set to '<code>*</code>' the position string of the original element is stored in the attribute <code>posattr</code> of the copied (extracted) element. If a XML doctype is defined for the original document it is applied to the target file. The element extraction is performed with the command [[Programmer_Guide/Shell_Items/File/SET_FILE#EXTRACTFILE|EXTRACTFILE]].
:Note: If the positions of the original elements are saved, the function <code>ResetSubDoc</code> must be used to reset the positions before the target file is deleted.


=====Result:=====
====ResetSubDoc====
;<code><var>bxmldoc</var> ResetSubDoc <var>file</var> ; <var>posattr</var></code>:
:;<var>file</var>: A XML containing extracted elements.
:;<var>posattr</var>: The name of element attribute for positions of original elements.
;Result: none
;Description: Reset the extracted file and all saved positions. This function must be called for all XML files created with EXTRACTSUBDOC.


An empty string for error/cancel or one of the values listed in the table below:
====DialogSelectElement====
 
<code><var>bxmldoc</var> DialogSelectElement <var>title</var> ; <var>selmode</var> ; <var>outmode</var> ; <var>tag1</var> ; <var>sub1</var> ; <var>tagX</var> ; <var>subX</var> ; ...</code>
{|
:;<var>title</var>: The dialog window caption.
|-
:;<var>selmode</var>: The selection mode {<code>SINGLE</code>|<code>MULTIMPLE</code>}.
|selmode
:;<var>outmode</var>: The output mode {<code>POSITION</code>|<code>IREF</code>}
|outmode
:;<var>tagX, subX</var>: The tag names and subtree scan flags which are passed to function <code>ExtractSubDoc</code>
|result
;Result: An empty string for error/cancel or one of the values listed in the table below:
::{|class="einrahmen"
!selmode !!outmode !!result
|-
|-
|SINGLE
|SINGLE
Line 361: Line 314:
|simple table containing internal references of selected elements
|simple table containing internal references of selected elements
|}
|}
 
;Description: Extracts a sub-document using the function <code>ExtractSubDoc</code> and displays the sub-document tree in a dialog where the user can select one or more elements (depending on <var>selmode</var>). Depending on <var>outmode</var>, either the position/s or the internal reference/s of the selected element/s is/are returned. If <var>outmode</var> is set to <code>POSITION</code> the user must cleanup the positions when the element processing is finished.
=====Examples:=====
;Examples: The following code displays a dialog with all audio files and sets in the current DataSet and retrieves the audio set information for the file chosen by the user (if any).
 
The following code displays a dialog with all audio files and sets in the current DataSet and retrieves the audio set information for the file chosen by the user (if any).


<pre>
<pre>
Line 376: Line 327:
end
end
</pre>
</pre>
===EXTRACTATTRIBUTELIST ref ; tag ; table ; attr1 ; ... ; attrN===
=====usage:=====
{|
|-
|ref
|parent element reference or * for current element
|-
|tag
|child element tag name or * for all elements
|-
|table
|target table for attributes or * to create a new table
if a table is specified, it must be an extended table;
the field 0 must be a string field and is used to store/check attribute names
|-
|attrX
|names of attributes to be excluded from the list
|}
=====result:=====
empty string (error) or extended table containing the list of attribute names in the first field; if a table was passed to the function, the same table is returned
=====description:=====
Extract all (different) attribute names from the child elements of the specified/current element. The attribute names are stored in the passed/created extended table. All attributes specified in the function call are excluded from the list.
===ExtractSubDoc===
Extract the elements with the specified tags from the document and copy them into the specified target file. The original tree structure is retained. The content of an element with tagX is only scanned if the corresponding <var>subX</var> argument is set to <code>1</code>. The element data are not extracted. If <var>posattr</var> is not set to '<code>*</code>' the position string of the original element is stored in the attribute <code>posattr</code> of the copied (extracted) element. If a XML doctype is defined for the original document it is applied to the target file. The element extraction is performed with the command "<code>SET xmlfile EXTRACTFILE ...</code>" (see command reference).
=====Usage:=====
<code>ExtractSubDoc <var>file</var> ; <var>posattr</var> ; <var>tag1</var> ; <var>sub1</var> ; <var>tag2</var> ; <var>sub2</var> ; ...</code>
=====Parameters:=====
;<var>file</var>
:The target XML file item for extracted elements.
;<var>posattr</var>
:The name of element attribute for positions of original elements.
;<var>tagX</var>
:The element tags to be extracted.
;<var>subX</var>
:Flag determining if child elements of <var>tagX</var> should be scanned scan too (yes=<code>1</code>, no=<code>0</code>).
=====Result:=====
none
===FINDBASE ref; res; attr1; ...===
=====usage:=====
{|
|-
|ref
|element reference or * for current element
|-
|res
|selects the type of the result (see description)
|-
|attrX
|list of attribute names to be retrieved
|}
=====result:=====
depends of argument res (see description)
=====description:=====
Find the base element of the current or specified element and return informations selected by argument res.
{|
|-
|res
|description
|result
|-
|SELECT
|select the base element and retrieve base element information
|'tag;children[;attr;..]'
|-
|INFO
|retrieve base element information but do not change current position
|'tag;children[;attr;...]'
|-
|SAVEPOS
|save position of base element but do not change current position
|'pos'
|}
with:
{|
|-
|tag
|base element tag
|-
|children
|number of children of base element
|-
|attr
|value of attributes specified in the command
|-
|pos
|position string of base element
|}
===FINDSETELEMENT tag ; id ; ref===
=====usage:=====
{|
|-
|tag
|element tag or * for any tag
|-
|id
|element id (wildcards are possible)
|-
|ref
|reference of set element or * for current element
|}
=====result:=====
0 for success or non<nowiki>-</nowiki>zero error code
=====description:=====
Find the (first element) with the specified tag (* = search all element tags) and id. For the matching of tag and id a case-sensitive comparison is used! If no ref is specified, the current level is searched from the beginning, otherwise the search is performed inside the specified set.
===FormatIRef===
Generates the internal XML reference string for the specified element at position <var>pos</var>. This string can only be created if all elements in the path except the root element have an ID attribute.
=====Usage:=====
<code>FormatIRef [ <var>pos</var> ]</code>
=====Parameters:=====
;<var>pos</var>
:The XML element position.
=====Result:=====
A reference to the selected element (IRef) or an empty string.
Last Modified: 18.06.2010 15:13:22
===ListSetElements===
Lists all element id's on the current level (ref=*) or inside the specified set element. If a table is passed, it is emptied before the id list is stored, otherwise a new table is created.
=====Usage:=====
<code><var>inst</var> ListSetElements <var>table</var>|* ; <var>iRef</var>|*</code>
=====Parameters:=====
;<var>table</var>
:A simple table to store element id's in or an asterisk for new table.
;<var>ref</var>
:The internal reference of a set element or an asterisk for the current element.
=====Result:=====
The id of a table containing the element id list.
=====Examples:=====
The <code>APar</code> function <code>GetAllUnitTypes</code> is implemented using the <code>ListSetElements</code> function.
<pre>
$BSTxIni Attach
$BSTxIni ListSetElements * ; '/Definitions/DataSet/Units'
if '$result[?]' == 'table' #result := $result
$BSTxIni Detach
exit 1 set '$#result'
</pre>
===LOAD [path]===
=====usage:=====
{|
|-
|path
|path of XML disk file to be loaded
|}
=====result:=====
0 for success or non<nowiki>-</nowiki>zero error code
=====description:=====
Loads the contents of the XML disk file. If no path is specified the path returned by GETPATH is used. If the function succeeds, the whole content is changed and all saved positions are deleted.
===LoadSetElement===
=====Usage:=====
<code><var>inst</var> LoadSetElement <var>tag</var> ; <var>id</var> ; <var>IRef</var>|*</code>
=====Parameters:=====
;<var>tag</var>
:The element tag (e.g. "<code>table</code>" for <code><table ID="screenColors" dim="2 4"></code>).
;<var>id</var>
:The element id (e.g. "<code>screenColors</code>" for <code><table ID="screenColors" dim="2 4"></code>).
;<var>IRef</var>
:The internal reference of the set to load or an asterisk for the current level.
=====Result:=====
A table containing loaded data or an empty string on failure.
=====Description:=====
Loads the data of the element with specified tag and id located inside the specified set. If the data are loaded, the specified element is selected, otherwise the position is not changed.
=====Examples:=====
Get the colors used to draw function lines 1 and 2 from the color scheme 'Color01':
<pre>
// get all values for the color scheme 'Color01'
#cScheme := set 'Color01'
#tColors := $($BStxIni LoadSetElement Table ; ScreenColors ; '/CurrentSetup/Global/Graphics/$#cScheme/')
if '$#tColors[?]' == 'table' then
    // extract color indices for function lines 1 and 2
    readstr '$#tColors[2]' #f1 #f2 #
    // convert indices to color keywords
    #colors := STXCONSTANTS COLORS
    #f1 := set $(word $#f1 $#colors)
    #f2 := set $(word $#f2 $#colors)
    // display color keywords in a dialog
    um f1 = $#f1 f2 = $#f2
    // clean up
    delete #tColors
else
    em -1 ; Failed to retrieve the screen colors for the $#cScheme color scheme.
end
</pre>
===ResetPos===
=====Usage:=====
<code><var>inst</var> ResetPos <var>pos</var>|<var>table</var> ; <var>field</var>|* [ ; <var>delelement</var> [ ; <var>deltable</var> ]]</code>
=====Parameters:=====
;<var>pos</var>
:The element position string.
;<var>table</var>
:A shell table containing element position strings.
;<var>field</var>
:The name of the field containing the element position strings (only used if <var>table</var> is an extended table).
;<var>delelement</var>
:Delete element flag: Set to <code>1</code> to delete elements, or <code>0</code> to do nothing (The default is <code>0</code>).
;<var>deltable</var>
:Delete table flag. Set to <code>1</code> to delete the table or <code>0</code> to do nothing (The default is <code>0</code>).
=====Result:=====
The number of errors or <code>0</code> for success
=====Description:=====
Delete the specified position <var>pos</var> or delete all positions stored in the specified table. If <var>delelement</var> is set to <code>1</code> then the associated elements are deleted too. If <var>deltable</var> is set to <code>1</code> and <var>table</var> is specified, then <var>table</var> is also deleted.
===RESETSUBDOC file ; posattr===
=====usage:=====
{|
|-
|file
|target XML file item for extracted elements
|-
|posattr
|name of element attribute for positions of original elements
|}
=====result:=====
none
=====description:=====
Reset the extracted file and all saved positions. This function must be called for all XML files created with EXTRACTSUBDOC.
===SAVE [path]===
=====usage:=====
{|
|-
|path
|path of output XML disk file
|}
=====result:=====
0 for success or non<nowiki>-</nowiki>zero error code
=====description:=====
Stores the document contents in the XML disk file. If no path is specified the path returned by GETPATH is used.
===SAVESETELEMENT object ; delete ; tag ; id ; ref===
=====Usage:=====
{|
|-
|object
|shell item containing data to be saved (table)
|-
|delete
|delete data object after save (0<nowiki>|</nowiki>1; def.=0)
|-
|tag
|element tag
|-
|id
|element id
|-
|ref
|reference of set or * for current level
|}
=====Result:=====
0 for success or non<nowiki>-</nowiki>zero error code
=====Description:=====
Save the object into the set element specified by tag, id and ref. If the element does not exist, a new element is created in the specified set. If the object is saved, the element is selected and the object is deleted (if delete is set to 1).
===SAVEPOS [oldpos]===
=====usage:=====
{|
|-
|oldpos
|element position string
|}
=====result:=====
position string for current element or empty string (if save position fails)
=====description:=====
Save the position of the current element and return the (unique) position string. If an oldpos is specified, the position identifier (not the element) is deleted.
===SELECT cmd [; tag ; attrexpr ; ...]===
=====usage:=====
{|
|-
|cmd
|find / select command
|-
|tag
|element tag name (* for all elements)
|-
|attrexpr
|attribute compare expressions (see command "SET xmlfile FIND ...")
|}
=====result:=====
0 for success or non<nowiki>-</nowiki>zero error code
=====description:=====
Selects the element specified by start, tag and attribute expressions. If the function returns 0 the specified element is selected, otherwise the current position is not changed.
{|
|-
|start
|description
|-
|ROOT
|goto root and find first element
|-
|OUT or PARENT
|step out of current element and find next element on parent level (only if a tag is specified), if no tag is specified the parent element is selected
|-
|IN or CHILD
|step into the current element and find first child
|-
|FIRST
|select / find first element
|-
|NEXT
|select / find next element
|-
|PREVIOUS
|select / find previous element
|-
|LAST
|select / find last element
|}
===SelectIRef===
=====Usage:=====
<code>inst SelectIRef <var>iref</var>|<var>pos</var>|<code>*</code> ; <var>in</var></code>
=====Parameters:=====
;<var>iref|pos|*</var>
:An element reference, an XML file item position string or an asterisk for the current element.
;<var>in</var>
:Go into selected element (<code>1</code>) or not (<code>0</code>). The default is <code>0</code>.
=====Result:=====
0 for success or a non-zero error code
=====Description:=====
Selects the element referred to by <var>iref</var> or <var>pos</var>. As reference a file item position string, an internal XML reference or the value * (= current element) can be used. If the element is selected successful and <var>in</var> equals <code>1</code> the child element level of the element is selected.
You can create an IREF for an element with the member function <code>FormatIRef</code>.
===TABLE2VARSPACE table ; del ; prefix ; inst===
=====Usage:=====
{|
|-
|table
|name of table containing variable settings
|-
|del
|delete table after conversion (0<nowiki>|</nowiki>1)
|-
|prefix
|prefix string for variable names
|-
|inst
|name of an instance item (optional)
|}
=====Result:=====
none
=====Description:=====
Converts the variable assignments stored in the table ("varname = varvalue") to variables. For each entry of the table a variable named "prefixvarname" is created and the value varvalue is assigned. If an instance item is specified the variables are stored as member variables of the instance, otherwise the variable space used to store the variables depends on the prefix (e.g. if prefix equals '@', the variables are stored as global variables). If the argument del is set to 1 the table is deleted after conversion. See VARSPACE2TABLE for conversion in the other direction.
===UNIQUEID===
=====Usage:=====
<code>inst UNIQUEID <var>pos</var>|<var>ref</var> ; <var>id</var>|* ; <var>ext</var> ; <var>start</var> ; <var>digits</var></code>
=====Parameters:=====
;<var>pos</var>
:The position of the parent element.
;<var>ref</var>
:The parent element's IREF.
;<var>id</var>
:The partial ID string. If an asterisk is specified, the ID is automatically generated.
;<var>ext</var>
:Use the counter in the ID extension (<code>yes</code>|<code>1</code>) or append the counter directly to the ID (<code>no</code>|<code>0</code>).
;<var>start</var>
:The counter start value. Use <code>-1</code> to test <var>id</var> without the counter suffix: if <var>id</var> is unique it is returned without any modifications.
;<var>digits</var>
:The number of digits. Use a value outside the range <code>2</code>-<code>9</code> to disable zero padding. If e.g. <var>digits</var> = 3, then the generated counter values will be <code>000</code>, <code>001</code>, <code>002</code>, etc.
=====Result:=====
A unique id string (unique on the selected level) or an empty string on failure.
=====Description:=====
Generate a unique id for the current level or inside the specified parent element. If <var>id</var> is unique, then <var>id</var> is returned. Otherwise, the counter is appended to <var>id</var> in the requested format.
===VARSPACE2TABLE table [; prefix; instance]===
=====Usage:=====
{|
|-
|table
|name of table containing variable settings
|-
|prefix
|prefix string for variable names
|-
|inst
|name of an instance item (optional)
|}
=====Result:=====


none
====Table2VarSpace====
;<code><var>bxmldoc</var> Table2VarSpace <var>table ; del ; prefix ; inst</var></code>:
:;<var>table</var>: name of table containing variable settings
:;<var>del</var>: delete table after conversion (<code>0</code>=yes, <code>1</code>=no)
:;<var>prefix</var>: prefix string for variable names
:;<var>inst</var>: name of an instance item (optional);
;Result: none
;Description: Converts the variable assignments (<code>varname = varvalue</code>) stored in the table to variables. For each entry of the table a variable named <var>prefix</var><code>varname</code> is created and the value <code>varvalue</code> is assigned. If an instance item <var>inst</var> is specified, the variables are stored as member variables of the instance, otherwise the variable space used to store the variables depends on the prefix (e.g. if prefix equals '@', the variables are stored as global variables). If the argument <var>del</var> is set to <code>1</code> the table is deleted after conversion. See <code>VarSpace2Table</code> for conversion in the other direction.


=====Description:=====
====VarSpace2Table====
;<code><var>bxmldoc</var> VarSpace2Table table ; prefix; inst</code>:
:;<var>table</var>: name of table containing variable settings
:;<var>prefix</var>: prefix string for variable names
:;<var>inst</var>: name of an instance item (optional);
;Result: none
;Description: Convert variables to table. Each entry of <var>table</var> must define one variable in the format <code>varname = varvalue</code>. The <code>varvalue</code> is replaced by the current value of the variable <var>prefix</var><code>varname</code>. If an instance item <var>inst</var> is specified the variables are read from the instance item, otherwise the variables must be stored in the global or the shell variable space. See VarSpace2Table for conversion in the other direction.


Convert variables to table. Each table entry must define one variable in the format 'varname = varvalue'. The varvalue is replaced by the current value of the variable prefixvarname. If an instance item is specified the variables are read from the instance item, otherwise the variables must be stored in the global or the shell variable space. See TABLE2VARSPACE for conversion in the other direction.
====AFun====
;<code><var>bxmldoc</var> AFun <var>memberFunctionName</var> [ ; <var>memberFunctionArgs</var> ]</code>:
;Result: result returned from member function call
;Description: This function attaches the XML document to the calling shell, executes the member function call <code><var>bxmldoc</var> <var>memberFunctionName</var> [ <var>memberFunctionArgs</var> ]</code> and detaches the XML document.

Latest revision as of 09:41, 1 October 2019

File: BXMLDOC.STX, linked to library STX.LIB
Parent class: CObj, Derived classes: BSTXIni, BDataSet

This class implements a general xml-document. It is mainly used to implement the common part of the two main STx documents: the project BDataSet and the workspace BSTXIni.

Construction

COBJ NEW BXMLDOC NEW|XNEW ; xmlobj|roottag [; aname=avalue; ...]
xmlobj
The name of a BXMLDoc-instance or the name of a XML-file-item.
roottag
The tag of the root element.
aname, avalue
The name and the value of a root element attribute.
Result
The created and initialized instance-item or an empty string
Description
Create a new empty XML document using the same root element tag as xmldoc or the specified roottag. During initialization the XML doctype is loaded, if it is defined in the STx configuration file, and the global item table is created. The XNEW variant creates or opens the XML file using the /Exclusive flag.


COBJ NEW BXMLDOC CREATE|XCREATE ; filepath; roottag [; aname=avalue; ...]
filepath
The name of the XML file.
roottag
The tag of the root element.
aname, avalue
The name and the value of a root element attribute.
Result
The created and initialized instance-item or an empty string
Description
Open an existing or create a new XML file and initialize the XML document. During initialization the XML doctype is loaded, if it is defined in the STx configuration file, and the global item table is created. If a new file is created, the root element with tag roottag and the specified attributes is created. The XCREATE variant creates or opens the XML file using the /Exclusive flag.


COBJ NEW BXMLDOC OPEN|XOPEN ; filepath
filepath
The name of the existing XML file.
Result
The created and initialized instance-item or an empty string
Description
Open an existing XML file and initialize the XML document. During initialization the XML doctype is loaded if it is defined in the STx configuration file and the global item table is created.


COBJ NEW BXMLDOC LINK ; xmlobj
xmlobj
The name of a BXMLDoc-instance.
Result
The created and initialized instance-item or an empty string
Description
Link the new XML document to the XML document xmlobj which was created and initialized in another shell. This constructor allows the sharing of XML documents between shells. This feature is f.i. used to share the global Workspace object ($BSTXIni) and the DataSet object ($BDataSet). Instances create with this method shares the file item and the global item table.

Access control

Because an BXMLDoc instance can be used by more than one shell, there must be a mechanism to control the access to the instance and its data content.

Attach

bxmldoc Attach [ iref ]
iref
Element reference or xml-position.
Result
name of file-item of the document
Description
Lock the XML document to the calling shell. The current position is saved. If an element reference or xml-position iref is specified, the member SELECTIREF is called to select the element. If a shell calls this function for the first time, the current XML file position is saved, for all further calls, only the lock-counter is increment.
This function should be called any time before a shell uses a shared XML document. If a shell issues more than one Attach function call, it must use the same number of Detach calls to unlock the XML document.

Detach

bxmldoc Detach
Result
1 if the xml-file-item was changed while it was locked and 0 if not. The return value is also 0 if the xml-file-item was not unlocked by the Detach function.
Description
Unlock the XML document from the shell and restores the element selected before the document was locked. If multiple Attach calls were used, the same number of Detach calls is necessary to really unlock the document.

Query attributes

GetFileItem

bxmldoc GetFileItem
Get the XML file item of the instance. The file should only be accessed directly if the XML document is locked to the shell (see #Access control). The use of the file item may be necessary to perform attribute access, element data access or special browse / search functions.
Result
the xml-file-item

GetDocType

bxmldoc GetDocType
Retrieve the name of the doctype if a doctype is defined for the root element of the XML file.
Result
name of XML doctype or empty string (if no doctype is defined for the document)

GetPath

bxmldoc GetPath
Retrieve the name of the XML file as stored on the hard drive. The result is empty if no file is associated with the document (this means the file exists in memory and was never loaded or saved). The function sets the &path member variable.
Result
the path of the the xml-file-item

File handling

Load

bxmldoc Load [ path ]
Load the content of the file path into the xml-file-item of the document. If path is not specified, the current path is used (see GetPath).
Result
0 for success or errorcode

Save

bxmldoc Save [ path ]
Save the xml-file-item of the document to the file path. If path is not specified, the current path is used (see GetPath).
Result
0 for success or errorcode

Close

bxmldoc Close [ save=0 [; path ] ]
Close the xml-file-item and delete the instance bxmldoc. If the argument save is set to 1, the document is saved before it is deletec (using the function call bxmldoc Save [ path ]).
Result
0 for success or errorcode (returned from Save).
Note
The instance bxmldoc is deleted, even if the function returns an errorcode.

Global items

This class implements some members to share items between shells. This feature is used f.i. by the application Viewer1 to implement the signal copy-paste functions and by some other applications.

AddGlobalItem

bxmldoc AddGlobalItem id ; item
id
The global id-string to use for item.
item
The shell-item to add to the global-item-list.
Result
0 for success or errorcode
Description
Add a shell item to the global item list. All items in the global item list can be linked by other shells, which have created a linked (shared) instance of this XML document. All types of items except displays, graphs and dialogs can be used.

AttachGlobalItem

bxmldoc AttachGlobalItem id [; lock=0 ]
id
The id-string of the global-item.
lock
If set to 1 the returned shell-item is locked.
Result
name of shell-item linked to the global-item or empty string
Description
Creates a linked instance (reference) of the global item with the specified id. If lock is set to 1 the linked instance is locked to the calling shell.

DetachGlobalItem

bxmldoc DetachGlobalItem item [; unlock=0 ]
item
A shell-item linked to a global-item.
unlock
If set to 1 the item is unlocked before it is deleted.
Result
no return value (void)
Description
Deletes a linked item. If unlock is set to 1 the linked item is unlocked before it is removed.

DeleteGlobalItem

bxmldoc DeleteGlobalItem id [; delete=0 ]
id
The id-string of the global-item.
delete
If set to 1 the shell-item is deleted.
Result
0 for success or errorcode
Description
Remove the global-item with id-string idfrom the global-item-list. If delete is set to 1, the item is deleted after removing from the list. An item can only be removed by the same shell that adds it to the list.

Element manipulation

AddElement

bxmldoc AddElement tag ; where ; goto ; attr=value ; ...
tag
The element tag.
where
Controls where the element should be created: create the element on the current level (CURRENT or 0) or as a child of the current element (CHILD or 1).
goto
Controls how the current position should be changed after the new element is created: select the created element (SELECT or 1), step into the created element (INSIDE or 2) or do not change the selected element (HOLD or 0).
attr=value
Name(s) and value(s) of attributes to be assigned to the new element. All name arguments must specifiy a valid XML attribute name.
Result
0 for success or errorcode
Description
Add a new element with the specified tag to the XML document. The element is added on the same level as the current element (where=CURRENT) or as child element (where=CHILD) of the current element. The attribute assignment attr=value are used to initialize the new elements attributes. If the function returns 0 the new element is created and the position is changed according to the argument goto, otherwise the document content and the current element position are not changed. To assign the attributes to the element the function call bxmldoc SetElement * ; attr=value ; ... is used.

SetElement

bxmldoc SetElement pos ; attrarg ; ...
pos
The xml-position or element reference of the element to be changed. The value * :;attrarg: Defines the name and the value of the attribute(s) to be set.
aname=avalue</value>: Assign the value avalue to the attribute aname. The aname must be a valid xml-attribute name. If avalue is empty, the attribute aname is deleted.
attrtab
The name of a simple-table containing one attribute setting aname = avalue per entry. This table gets deleted after processing!
Result
0 for success or errorcode.
Description
Set the attributes of a specific element. The current position is not changed by this function. An error is returned, if no element is found at the specified position pos, or an attribute assignment fails. If an error is returned, some attributes of the element may be changed! To remove an attribute, an empty attribute value can be used ( aname=; ).

GetElement

bxmldoc GetElement pos ; info ; aname1 ; ...
pos
The xml-position or element reference of the element.The value * can be used for the element at the current position.
info
0 get attribute values result = avalue1; ...
1 get element tag and attribute values :result = tag; avalue1; ...
2 get element tag, number of children and attribute values result = tag; nchildren; avalue1; ...
aname1, ...
list of attribute names
Result
empty string (element not found) or a string containing selected informations (see argument info)
Description
Retrieve general informations about the specified element and/or element attribute values. The current element position is not changed by this function.

DeleteElement

bxmldoc DeleteElement pos
pos
The xml-position or element reference of the element.The value * can be used for the element at the current position.
Result
0 for success (deleted) or 1 for error
Description
Delete the selected element. The current element position is only changed, if the current element was deleted.

Data manipulation

GetDataType

bxmldoc GetDataType [ tag ]
tag
The element tag to be tested; if not specified or set to * the tag of the current element is used.
Result
The data type defined in the doctype or the element tag if no data type is defined for the specified tag.
Description
Returns type of date stored in elements with the specified tag. This function is used by LoadData and SaveData to retrieve data type information. In the current doctype-version only the types TABLE and 'XTABLE tabledef' are supported.

CreateXTable

bxmldoc CreateXTable typedef [ fname1 ... ]
typedef
The name (ID) of the XTableTypeDef element.
fname1, ...
The name of the extra fields to be added to the extended table.
Result
The name of the new and initialized extended table-item or an empty string.
Description
Creates an extended table using the specified typedef or retrieves data type information for the current element (if no typedef is specified). If extra fields are specified and the typedef contains a definition statement for the extra fields, they are added to the table.
Note
A typedef for an extended table is defined in an xml element with the tag XTableTypeDef with the attribute ID="typedef". This element must be defined in the definition-section of the STx configuration file or on level of the current element.

LoadData

bxmldoc LoadData
Result
The name of the shell-item (table) containing the loaded data or an empty string.
Description
Loads the data stored in the current element. The item for the data is created in the function and returned to the caller. Data type information is retrieved by calling GetDataType and CreateXTable.
Example
Load data from the STx configuration file at the IRef /Definitions/DataSet/Methods.
...
$bstxini attach
$bstxini selectiref '/Definitions/DataSet/Methods'
if '$result' == 0 #data := $bstxini loaddata
$bstxini detach
...

SaveData

bxmldoc SaveData item [ ; del=0 ]
item
Shell-item (table) containing the data to be saved.
del
If set to 1 the shell-item is deleted after saving
Result
0 for success or errorcode
Description
Save item into the data section of the current element. The data format is selected by calling GetDataType. The item is only saved, if it is valid for the data type. If item is saved successful and del is set to 1, item is deleted.


IRef functions

  • This group of functions was originally developed, to deal with unique references to elements of type Set with the special unique id attribute ID. This implementation was modified, because the attribute ID is now used as a unique identifier for elements of any type.
  • A string in the format /id1/id2/.../idn is called IRef (for "(unique) Internal REFerence"). This string is interpreted as follows:
    • id1 is the unique element id (value of attribute ID) on the root-level
    • id2 is the unique element id inside the element selected by id1
    • and so on

SelectIRef

bxmldoc SelectIRef [ pos=* ; in=0 ]
pos
An (unique internal) element reference, a xml-position or the character * for the current element.
in
Go into the selected element (1) or not (0).
Result
0 for success or an errorcode
Description
Selects the element referred to by pos. If the element is selected successfully and in equals 1, the child element level of the element is selected. You can create an IRef for an element with the member function FormatIRef.
see also
commands IREF and POSITION

FormatIRef

bxmldoc FormatIRef [ pos=* ]
pos
The XML element position or * for the current element.
Result
A reference (IRef) to the selected element or an empty string.
Description
Generates the internal XML reference string for the specified element at position pos. This string can only be created if all elements in the path except the root element have an ID attribute.
see also
commands IREF and POSITION

UniqueID

bxmldoc UniqueID [ pos=* ; id=* ; ext=0 ; start=-1 ; digits=0 ]
pos
The position/reference of the parent element (* = current element)
id
The fixed part of the id-string. If an asterisk is specified, the string "Auto" is used.
ext
Use the counter in the id-extension (yes or 1) or append the counter directly to the id-string (no or 0).
start
The counter start value. Use -1 to test id without the counter suffix: if id is unique it is returned without any modifications.
digits
The number of digits. Use a value outside the range 2..9 to disable zero padding. If e.g. digits equals 3, the generated counter values will be 000, 001, 002, etc.
Result
A unique id string (unique on the selected level) or an empty string on failure.
Description
Generate a unique id for the current level or inside the specified parent element. If id is unique, then id is returned. Otherwise, the counter is appended to id in the requested format.

"Set" functions

  • This group of functions was originally developed to deal with elements of type Set with the special unique id attribute ID. This implementation was modified, because the attribute ID is now used as a unique identifier for elements of any type.

ListSetElements

bxmldoc ListSetElements [ table=* ; iref=* ]

table
simple table-item to store result; if * is used a new table is created
iref
reference of the set-element containing the elements to be listed; use * for the current level
Result
the table-item containing the result (list of id's) or an empty string
Description
Lists all element id's on the current level (iref=*) or inside the specified set-element. If a table-item is passed, it is emptied before the id list is stored, otherwise a new table is created.

FindSetElement

bxmldoc FindSetElement [ tag=* ; id=* ; iref=* ]

tag
element tag; use * for all elements
id
value of ID attribute; wildcards are possible
iref
reference of the set-element to be searched; use * for the current level
Result
0 if the element was found and 1 if not
Description
Find the (first element) with the specified tag (* = search all element tags) and id. For the matching of tag and id a case-sensitive comparison is used! If no iref is specified, the current level is searched from the beginning, otherwise the search is performed inside the specified set.

AddSetElement

bxmldoc AddSetElement [ tag ; id ; iref=* ]

tag
element tag
id
element id (value of ID attribute)
iref
reference of the set-element where the element should be created; use * for the current level
Result
0 if the element was selected/created and 1 if not
Description
Create a new element with specified tag and id in the set selected by iref. If the specified set does not exist, it will be created. If a set must be created, for each set element the tag SET is used by default, but it is possible to specify another tag in the argument ref with the format: /setid/.../settag:setid/.../. If the element is created, the new element is selected, otherwise the position is not changed. If the element exists already, it is selected but not changed.

LoadSetElement

bxmldoc LoadSetElement [ tag=* ; id=* ; iref=* ]

Result
The loaded data object (table-item, value returned from LoadData) or an empty string.
Description: This function uses the call bxmldoc FindSetElement tag;id;iref to select the element and the call bxmldoc LoadData to load the content of the selected element. If element selection or loading data failes (error), the file position is not changed, otherwise (success) the loaded element is selected.

SaveSetElement

bxmldoc SaveSetElement [ item ; del=0 ; tag=* ; id=* ; iref=* ]

Result
0 if the data item was saved successful and 1 otherwise
Description: This function uses the call bxmldoc AddSetElement tag;id;iref to select or create the element and the call bxmldoc SaveData to save the item into the element. If element selection or save operation failes (error), the file position is not changed, otherwise (success) the created/updated element is selected.

DeleteSetElement

bxmldoc DeleteSetElement [ tag=* ; id=* ; iref=* ]

Result
0 if the element was deleted and 1 otherwise
Description: This function calls bxmldoc FindSetElement tag;id;iref to select an element and than deletes the selected element.

Misc

SavePos

bxmldoc SavePos [ delpos=* ]

Result
current xml position id or empty string if position can not be saved (no element selected)
Description
Returns the xml position id of the currently selected element. If the xmp position id delpos is not equal *, this position is closed (reset).
See Also
POSITION

ResetPos

bxmldoc ResetPos pos=* [ ; * ; delemem=0 ]

Result
always 0
Description
Restore the the xml position id pos. If delelem equals 1 the element at the restored position is deleted.


bxmldoc ResetPos table=* [ ; row=* ; delemem=0 ; deltable=0 ]

Result
always 0
Description
Restore all xml positions stored in table[*,row]. If table is a simple table, the argument row is ignored.
  • If delelem equals 1 the elements at the restored positions are deleted
  • If deltable equals 1 the table is deleted
  • This function can be used to reset positions returned by FIND or EXTRACTTABLE commands.

ExtractSubDoc

bxmldoc ExtractSubDoc file ; posattr ; tag1 ; sub1 ; tag2 ; sub2 ; ...
file
The target XML file item for extracted elements.
posattr
The name of element attribute for positions of original elements.
tagX
The element tags to be extracted.
subX
Flag determining if child elements of tagX should be scanned scan too (yes=1, no=0).
Result
none (void), file contains extracted elemenents
Description
Extract the elements with the specified tags from the document and copy them into the specified target file. The original tree structure is retained. The content of an element with tagX is only scanned if the corresponding subX argument is set to 1 (or yes). The element data are not extracted. If posattr is not set to '*' the position string of the original element is stored in the attribute posattr of the copied (extracted) element. If a XML doctype is defined for the original document it is applied to the target file. The element extraction is performed with the command EXTRACTFILE.
Note: If the positions of the original elements are saved, the function ResetSubDoc must be used to reset the positions before the target file is deleted.

ResetSubDoc

bxmldoc ResetSubDoc file ; posattr
file
A XML containing extracted elements.
posattr
The name of element attribute for positions of original elements.
Result
none
Description
Reset the extracted file and all saved positions. This function must be called for all XML files created with EXTRACTSUBDOC.

DialogSelectElement

bxmldoc DialogSelectElement title ; selmode ; outmode ; tag1 ; sub1 ; tagX ; subX ; ...

title
The dialog window caption.
selmode
The selection mode {SINGLE|MULTIMPLE}.
outmode
The output mode {POSITION|IREF}
tagX, subX
The tag names and subtree scan flags which are passed to function ExtractSubDoc
Result
An empty string for error/cancel or one of the values listed in the table below:
selmode outmode result
SINGLE POSITION position string of selected element
SINGLE IREF internal reference of selected element
MULTIPLE POSITION simple table containing position strings of selected elements
MULTIPLE IREF simple table containing internal references of selected elements
Description
Extracts a sub-document using the function ExtractSubDoc and displays the sub-document tree in a dialog where the user can select one or more elements (depending on selmode). Depending on outmode, either the position/s or the internal reference/s of the selected element/s is/are returned. If outmode is set to POSITION the user must cleanup the positions when the element processing is finished.
Examples
The following code displays a dialog with all audio files and sets in the current DataSet and retrieves the audio set information for the file chosen by the user (if any).
#pos := $BDataSet DialogSelectElement title ; single ; position ; Set ; 1 ; AFile ; 0
if '$#pos' != '' then
    readstr '$($BDataSet GetASetInfo $#pos soundfile)' #sf';'#setId';'#srate';'#ch';'#fPath
    if '$#fPath' != '' #file := $#fPath
    if '$#sRate' != '' #sr := $#srate
    #iref := $($BDataSet FormatIRef $#pos)
    #result := '$#file ; $#sr ; $#iref ; $#ch'
end

Table2VarSpace

bxmldoc Table2VarSpace table ; del ; prefix ; inst
table
name of table containing variable settings
del
delete table after conversion (0=yes, 1=no)
prefix
prefix string for variable names
inst
name of an instance item (optional);
Result
none
Description
Converts the variable assignments (varname = varvalue) stored in the table to variables. For each entry of the table a variable named prefixvarname is created and the value varvalue is assigned. If an instance item inst is specified, the variables are stored as member variables of the instance, otherwise the variable space used to store the variables depends on the prefix (e.g. if prefix equals '@', the variables are stored as global variables). If the argument del is set to 1 the table is deleted after conversion. See VarSpace2Table for conversion in the other direction.

VarSpace2Table

bxmldoc VarSpace2Table table ; prefix; inst
table
name of table containing variable settings
prefix
prefix string for variable names
inst
name of an instance item (optional);
Result
none
Description
Convert variables to table. Each entry of table must define one variable in the format varname = varvalue. The varvalue is replaced by the current value of the variable prefixvarname. If an instance item inst is specified the variables are read from the instance item, otherwise the variables must be stored in the global or the shell variable space. See VarSpace2Table for conversion in the other direction.

AFun

bxmldoc AFun memberFunctionName [ ; memberFunctionArgs ]
Result
result returned from member function call
Description
This function attaches the XML document to the calling shell, executes the member function call bxmldoc memberFunctionName [ memberFunctionArgs ] and detaches the XML document.
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Macro_Library/BXMLDoc&oldid=10654"

Navigation menu

Personal tools