DataSetCmd

From STX Wiki
Jump to navigation Jump to search

This macro implements an interface to send a command to the DataSet application (the STx Workspace). It can only be used whilst the DataSet application is running.

Before a DATASETCMD function is called, the Workspace object ($BSTXINI) and the DataSet object ($BDATASET) must be unlocked (detached) if they were locked (attached) by the calling application. If one of these objects is locked, a deadlock situation may occur.

Note: The up-to-date description of important DataSetCmd functions for user script programming can be found here.

General Usage

DATASETCMD subcommand [ args ]

subcommand
The command to be sent to the DataSet application.
args
The command specific arguments (see below).

The DATASETCMD command alone does not return a result. The following subcommands are implemented.

GETSELECTED

Retrieve a list of selected segments or parameters from the Workspace Detail. Note that this command can only be called from the BScript environment (i.e. a script).

Usage:

#list := DATASETCMD GETSELECTED SEGMENTS

Result:

A table where each entry has the following format:

audioSetIref ; audioSegmentId ; audioChannelAttributeValue

Usage:

#list := DATASETCMD GETSELECTED PARAMETERS

Result:

A table where each entry has the following format:

audioSetIref ; audioSegmentId ; indexOfAnalysedChannel ; parameterMethodName ; parameterType

Usage:
#list := DATASETCMD GETSELECTED SETS
Result:

A table where each entry has one of the following formats, depending on the set type (AFile, ASequence, ASegList or Set):

AFile ; elementId ; elementIref ; samplingRate ; numberOfChannels ; fullFilePath

ASequence ; elementId ; elementIref ; samplingRate ; numberOfChannels

ASegList ; elementId ; elementIref

Set ; elementId ; elementIref



SETSELECTED

Selects an audio-set element in the Overview (by IREF) and select segments in the Detail (by ID). Note that this command currently only works for AFile and ASegList audio sets.

Usage:

DATASETCMD SETSELECTED iref ; segList

Parameters:
iref
The IREF to an audio set element.
segList
A semi-colon separated list of segment IDs in the element referenced by iref.



SELECTSCRIPT

Shows a dialog to select a script file in the Script Controller.

Usage:

DATASETCMD SELECTSCRIPT [ defaultFile ]

Result:

An empty string.



NEWDATASET

Opens a dialog to create a new (empty) DataSet file.

Usage:

DATASETCMD NEWDATASET [ fileName ]

Parameters:
fileName
The file name to use for the new DataSet. If no file name is specified, the user is asked to specify one.
Result:

An empty string if successful, or an error code on failure.



OPENWORKSPACE

This function should not be used by script programmers!

SAVEWORKSPACE

Saves the workspace to disk.



SAVEWORKSPACEAS

Displays a dialog prompting the user to save the workspace to a new file.



OPENDATASET

Displays a dialog prompting the user to select an existing DataSet file to open.



SAVEDATASET

Save the project file to disk.

Usage:

DATASETCMD SAVEDATASET [ auto ]

Set auto to 1 if the project should be saved without asking the user for confirmation.

Result:

An empty string.

SAVEDATASETAS

Display a dialog prompt the user to save the DataSet to a new file.



EXIT

Close the Workspace application.

OPENMENU

This function should not be used by script programmers!

CLOSEMENU

This function should not be used by script programmers!

REFRESHMENU

This function should not be used by script programmers!

REFRESHDETAIL

Update the Detail window of the DataSet browser.

REFRESHALL

Update the DataSet and Application & Setup Tree windows.



NEWSCRIPT

Shows a dialog to create a new script file.

Usage:

DATASETCMD NEWSCRIPT [ par ]

Parameters:
par
If par 1 is passed, the script is opened for editing (default). If a global variable is passed, then the new script name is stored in the variable. If not, the script is imported into the Script Controller.
Result:

An empty string if successful, or an error code on failure.



EDITSCRIPT

Starts the application associated with the script file for editing.



TESTSCRIPT

Tests the source code of the selected script.



GETSCRIPTINFO

This function should not be used by script programmers!

SETSCRIPTINFO

This function should not be used by script programmers!

SD0UPDATE

This function should not be used by script programmers!

DIALOGLAYOUT

Browser display layout dialog.



DIALOGGETATTRIBUTES

Update attribute dialog.



SAVECONTEXT

This function should not be used by script programmers!

RESTORECONTEXT

This function should not be used by script programmers!

AUTOSAVE

Turns the DataSet autosave feature on and off.

Usage:

DATASETCMD AUTOSAVE ON|OFF

Array