BXMLDoc - General XML Document

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.