BXMLDoc

From STX Wiki
Jump to navigationJump to search

This class implements a general XML document.

Parent class
CObj
Derived classes
BSTXIni, BDataset
Content
#Construction, #Access control, #Query attributes, #File handling, #Global items

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.


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


bxmldocDetach
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

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


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)


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

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


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


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.


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


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


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


bxmldocAttachGlobalItem 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

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




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.


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.


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.


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

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.


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.

Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Macro_Library/BXMLDoc&oldid=5269"

Navigation menu

Personal tools