Programmer Guide/Macro Library/BXMLDoc

This class implements a general XML document.

Parent class

CObj

Derived classes

BSTXIni, [Programmer Guide/Class Library/BDataset|BDataset]]

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.

CONSTRUCT NEW|XNEW

Create a new empty XML document using the same root element tag as the XML document 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 XCREATE variant creates or opens the XML file using the /Exclusive flag (see the file item for details).

Usage:

CONSTRUCT NEW|XNEW ; xmldoc|roottag ; attributes

Parameters:

xmldoc

The name of a BXMLDoc instance.

roottag

The root element tag.

attributes

The attributes to be added to the root element, in the format

AName=AValue ; BName=BValue ...

Result:

0 for success or a non-zero number for error

CONSTRUCT OPEN|XOPEN

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.

Usage:

CONSTRUCT OPEN|XOPEN ; filepath

Parameters:

filepath

The name of an existing XML file.

Result:

0 for success or a non-zero number for error.

CONSTRUCT LINK

Link the new XML document to the XML document xmldoc 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.

Usage:

CONSTRUCT LINK ; xmldoc

Parameters:

xmldoc

The name of the BXMLDoc instance.

Result:

0 for success or a non-zero number for error.

Add a new element with the specified tag to instance's 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.

Usage:

inst AddElement tag ; where ; goto ; attr=value ; ...

Parameters:

tag

The element tag.

where

Create the element on the current level (CURRENT|0) or as a child of the current element (CHILD|1).

goto

Select the created element (SELECT|1), step into the created element (INSIDE|2) or do not change the selected element (HOLD|0).

attr

The name of attribute. The name must be a valid XML attribute name.

value

The value to assign to the attribute attr.

Result:

0 for success or non-zero error code

ADDGLOBALITEM

Usage:

ADDGLOBALITEM id ; item

Parameters:

id

The global id to use.

item

The id of the item to add to the global item list.

Result:

0 for success or non-zero error code

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.

AddSetElement

Create a new element with specified tag and id in the set selected by ref. 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.

Usage:

inst AddSetElement tag ; id ; ref

Parameters:

tag

The element tag. E.g. 'ASet'.

id

The element id. E.g. <ASet ID='myId'>

ref

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.

ATTACH [ref]

Usage:

ref	element reference

Result:

name of file item of the XML document

Description:

Lock the XML document to the calling shell. The current position is saved. If an element reference ref 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.

The ATTACH 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.

ATTACHGLOBALITEM id ; lock

usage:

id	global item id name
lock	lock the linked item (0|1, def.=0)

result:

name of attached (linked) item or empty string

description:

Creates a linked instance of the global item with the specified id. If lock is set to 1 the linked instance is locked to the calling shell.

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

CreateXTable

Creates an extended table using the specified typedef or retrieves data type information for the current element (if no typedef is specified). The typedef for the extended table must be defined in the STx configuration file. If extra fields are specified and the typedef contains a definition statement for the extra fields, they are added to the table.

Usage:

CreateXTable [ typedef ; field1 ; field2 ; ... ]

<kp

typedef

The name of the XTableTypeDef element.

fieldX

The name of the extra fields to be added to the extended table.

Result:

The name of the new and initialized extended table or an empty string.

DeleteElement

Usage:

inst DeleteElement ref|*

Parameters:

ref

The element IRef or an asterisk for the current position.

Result:

0 for success or non-zero error code

Description:

Delete the selected element. The current element position is only changed, if the current element was deleted.

DELETEGLOBALITEM id ; delete

usage:

id	global item id name
delete	delete item (0|1, def.=0)

result:

0 for success or non-zero error code

description:

Remove the global item with name id from 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.

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

DETACH

result:

lock counter (>= 1) or empty string if XML document was unlocked

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.

DETACHGLOBALITEM item ; unlock

usage:

item	name of linked item (created with ATTACHGLOBALITEM)
unlock	unlock before delete (0|1, def.=0)

result:

none

description:

Deletes a linked item. If unlock is set to 1 the linked item is unlocked before it is removed.

DialogSelectElement

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.

Usage:

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

Parameters:

title

The dialog window caption.

selmode

The selection mode {SINGLE|MULTIMPLE}.

outmode

The output mode {POSITION|IREF}

tagX, subX

The tag name and subtree scan flag, are passed to function ExtractSubDoc. Note that

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

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

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 subX argument is set to 1. 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 "SET xmlfile EXTRACTFILE ..." (see command reference).

Usage:

ExtractSubDoc file ; posattr ; tag1 ; sub1 ; tag2 ; sub2 ; ...

Parameters:

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

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-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 pos. This string can only be created if all elements in the path except the root element have an ID attribute.

Usage:

FormatIRef [ pos ]

Parameters:

pos

The XML element position.

Result:

A reference to the selected element (IRef) or an empty string.

Last Modified: 18.06.2010 15:13:22===GetDataType===

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.

Usage:

GetDataType [ tag ]

Parameters:

tag

The element tag to be tested; if not specified the tag of the current element is used.

Result:

The data type define in the doctype or element tag if no data type is defined for the specified tag

GETDOCTYPE

result:

name of XML doctype or empty string (if no doctype is defined for the document)

description:

Retrieve the name of the doctype if a doctype is defined for the root element of the XML file.

GETELEMENT ref ; info ; attr ; ...

usage:

ref	element reference or * for current element
info	info selection (0 – 2)
attr	attribute names

result:

empty string for error or

info == 0 'attrvalue1 ; attrvalue2; ...'

info == 1 'tag ; attrvalue1 ; attrvalue2; ...'

info == 2 'tag ; children ; attrvalue1; attrvalue2; ...'

description:

Retrieve general informations about the specified element and/or element attribute values. The current element position is not changed by this function.

GETFILEITEM

result:

name of XML file item of the XML document

description:

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 member ATTACH). The use of the file item may be necessary to perform attribute access, element data access or special browse / search functions.

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.

Usage:

inst GetPath

Result:

The full pathname of the XML disk file belonging to the document or an empty string.

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:

inst ListSetElements table|* ; iRef|*

Parameters:

table

A simple table to store element id's in or an asterisk for new table.

ref

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 APar function GetAllUnitTypes is implemented using the ListSetElements function.

$BSTxIni Attach
$BSTxIni ListSetElements * ; '/Definitions/DataSet/Units'
if '$result[?]' == 'table' #result := $result
$BSTxIni Detach
exit 1 set '$#result'

LOAD [path]

usage:

path	path of XML disk file to be loaded

result:

0 for success or non-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.

LoadData

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. You can navigate to a specific element using the function SelectIRef.

Usage:

inst LoadData

Result:

The name of item containing loaded data or an empty string if load fails.

Examples:

Load data from the current STx INI file at the IRef '/Definitions/DataSet/Methods'.

$bstxini attach
$bstxini selectiref '/Definitions/DataSet/$#argv'
if '$result' == 0 then
        #data := $($BSTXIni loaddata)
end
$bstxini detach

LoadSetElement

Usage:

inst LoadSetElement tag ; id ; IRef|*

Parameters:

tag

The element tag (e.g. "table" for ).

id

The element id (e.g. "screenColors" for

).

IRef

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':

// 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

ResetPos

Usage:

inst ResetPos pos|table ; field|* [ ; delelement [ ; deltable ]]

Parameters:

pos

The element position string.

table

A shell table containing element position strings.

field

The name of the field containing the element position strings (only used if table is an extended table).

delelement

Delete element flag: Set to 1 to delete elements, or 0 to do nothing (The default is 0).

deltable

Delete table flag. Set to 1 to delete the table or 0 to do nothing (The default is 0).

Result:

The number of errors or 0 for success

Description:

Delete the specified position pos or delete all positions stored in the specified table. If delelement is set to 1 then the associated elements are deleted too. If deltable is set to 1 and table is specified, then table 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-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.

SAVEDATA item ; delete

usage:

item	item containing data to be saved
delete	delete item (0|1; def.=0)

result:

0 for success or non-zero error code

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 the item is saved successful and delete is set to one, the item is deleted.

SAVESETELEMENT object ; delete ; tag ; id ; ref

Usage:

object	shell item containing data to be saved (table)
delete	delete data object after save (0|1; def.=0)
tag	element tag
id	element id
ref	reference of set or * for current level

Result:

0 for success or non-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-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:

inst SelectIRef iref|pos|* ; in

Parameters:

iref|pos|*

An element reference, an XML file item position string or an asterisk for the current element.

in

Go into selected element (1) or not (0). The default is 0.

Result:

0 for success or a non-zero error code

Description:

Selects the element referred to by iref or pos. 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 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.

SETELEMENT

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 value can be used (attr=; ).

Usage:

inst SETELEMENT pos|* ; attr[=value] ; ...

inst SETELEMENT pos|* ; tablei ; ...

Parameters:

ref

The position of the element, or * for the current position.

attr

An attribute name.

value

An attribute value to assign to the preceding attr.

tablei

A table containing "attr=name" strings. This table gets deleted after processing!

Result:

0 for success or non-zero error code

TABLE2VARSPACE table ; del ; prefix ; inst

Usage:

table	name of table containing variable settings
del	delete table after conversion (0|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:

inst UNIQUEID pos|ref ; id|* ; ext ; start ; digits

Parameters:

pos

The position of the parent element.

ref

The parent element's IREF.

id

The partial ID string. If an asterisk is specified, the ID is automatically generated.

ext

Use the counter in the ID extension (yes|1) or append the counter directly to the ID (no|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 = 3, then 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.

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

Description:

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.