BXMLDoc - General XML Document

From STX Wiki
Jump to navigation Jump to search
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.