Programmer Guide/Macro Library/BDataSet

File: BDataSet.STX, linked to library STX.LIB

See also: BXMLDoc, BSTXIni, DataSetCmd

This class implements the project document. The project document is the global database available to all STx applications and scripts and contains all data and links of the current project. The content of the project document is stored in a XML file item The programmer must not create or destroy the project object because these functions are performed by the application startup and cleanup macros.

Never ever call the member functions CONSTRUCT, DESTRUCT or CLOSE!

At application startup a BDataSet instance is created and linked to the global project document which is created and managed by the STx master shell. The name of this instance is stored in the shell variable BDATASET. This object must be used to access the project document.

The class BDataSet is derived from the class BXMLDoc. Beware of using the base class functions, since they do not update the BDataSet member variables! No static commands are implemented by this class; a call to the macro BDataSet (e.g. bdataset save) will do nothing, returning an empty string.

Before a shell or a script uses or changes the content of the project document, it should be attached (locked) using the function call $bdataset attach (see: Attach & Detach).

Attach & Detach

Usage

$bdataset attach [ iref ]

$bdataset detach

iref

reference or position of an element of the project document, if specified the element is selected after attaching

Result

the name of the xml-file item containing the project document data

Description

The function attach locks the project document and returns the internal xml-file item containing the project data. Only the calling shell can now access the project content, all other shells are blocked. The project document remains locked until the next call to detach. Multiple calls of attach (by the same shell) are possible, but for each call also the function detachmust be called.

Example

// first attach call - lock project document and save current xml-position (pos1)
$bdataset attach
... 
//	second attach call - save xml-position (pos2)
$bdataset attach
...
// first detach call - restore xml-position pos2, project document remains locked!
$bdataset detach
...
//	second detach call - restore xml-position pos1 and unlock project document, 
//	if the project document was changed by the code between first attach and second detach,
// the message "DATASETCHANGED" is sent to all running shells
$bdataset detach

Project Properties

isNewFile

Usage

$bdataset isnewfile

Result

1 if the project file is new (not named and not saved) and 0 otherwise.

GetPath

Usage

$bdataset getpath

Result

the full path of the project file or an empty string

SetLink

Usage

$bdataset setlink mode

mode</mode>: 0 (or no) to set project to not linked and 1 (or yes) to set it to linked

Result

0 if the selected mode was enabled and 1 if the function fails.

Description

This function changes the project attribute AFile (attribute of the root-element STXDataSet).

• AFile=Link: The project is in mode linked. The segment metadata are stored in STx metadata files, which are xml-files with the same pathname as the sound file and the filetype stxsm. The segment metadata files of sound file linked to the project are loaded/saved automatically, when the project is loaded/saved. The project file contains only links to the sound files of the project.
• AFile is not assigned: The project is in mode not linked. All data of the project, including segment metadata, are stored in the project file. A project in this mode may contain multiple links to one sound file (e.g. to manage different segmentations of the same signal).

=

Undocumented Functions

• getBaseDirecory - used by memeber function Save to verify file path