Programmer Guide/Macro Library/ADesc

ADesc - Parameter Description Classes

All classes for storing parameters are derived from ADesc. ADesc itself is a very general class suited for any kind of parameter with any number and kind of axes. Being general generally means being slow which surely holds true for the ADesc class. So for most (if not any) practical applications, you will most likely want to use one of its derived classes tailored to several important special cases. At this time, there are the following kinds of ADesc-classes:

ADesc1 - handles only parameters with exactly ONE independent axis, but handles them well and fast.

ADesc2 - handles only parameters with exactly TWO independent axes, but it does so rather well and at a considerable speed.

ADesc0 - handles only parameters WITHOUT independent axes.

ADesc - is the general class. It handles everything the other classes don't handle, but it does so at a high price indeed.

ADescX - is functionally equivalent to ADesc. It organizes the data in a different way and currently proves more performance than ADesc. This may change as table handling in STx changes over time.

When creating a new parameter, you will have to specify which one to create. You may do so either by calling the static "New" function of the ADesc class of your choice, e.g. "ADesc2 new" for creating an ADesc2 instance.

ADesc Types

There are 5 ADesc variants:

• ADesc - The base class for all other axis classes. You are probably better off using one of the derived classes.
• ADesc1 - An efficient class to model parameters with one independent axis and any number of dependent axes.
• ADesc2 - A class to model parameters with two independent axes and any number of dependent axes.
• ADesc0 - A class to model parameters without any independent axes and a constant dependent axis.
• ADescX - A class to model parameters with any number of independent axes and any number of dependent axes.

ADesc1

ADesc1 is an efficient class for manipulating parameters with exactly one independent axis and an arbitrary number of dependent axes. Tests have shown that this class can comfortably deal with parameters with hundreds of thousands of values.

Setting and retrieving data

The ADesc1 class provides many functions to set and retrieve data. The following are recommended:

setValue, getValue, setValues, getValues, setNativeValues and getNativeValues.

Die bevorzugten Zugriffsfunktionen von ADesc1 sind setValue/getValue, setValues/getValues und setNativeValues/getNativeValues. Letztere arbeiten im Fall der ADesc1-Klasse mit einem Wertevektor als natürlichem Achsenformat, d.h. mit einer einspaltigen STX-Parametertabelle, die für die unabhängige Achse alle Werte der gewünschten abhängigen Achse enthält. Die Einheitenumrechnung erfordert einen gewissen zusätzlichen Rechenaufwand, der aber durch das Verwenden der nativen Einheit vermieden werden kann.

ABaseClass : CObj

ABaseClass is the base class of all kinds of ADesc classes. Its sole purpose is providing for configurable logging functions. Depending on which of the following variables are set to 1 or to 0, messages are logged in different ways. These logging methods are not mutually exclusive. Therefore it is e.g. possible to show error messages both in the STx log and in dialog boxes (which, by chance, is the default behaviour).

ABaseClass modifies the shell variables aDescError and aDescLogOpts. See aDescError and aDescLogOpts for details.

It is not necessary for derived classes to call the constructor and destructor of this class, because both functions do nothing.=====aDescError=====

If the last ADesc command failed, the shell variable aDescError contains a descriptive error message. If the last ADesc command was successful, aDescError contains an empty string.

aDescLogOpts

The class ABaseClass (and therefore all the ADesc classes) display error messages based on the contents of the shell variable aDescLogOpts. The variable contains three space separated numerical values:

aDescLogOpts = log con box

If log is set to 1, messages are displayed in the STx log-window. If con is set to 1, messages are displayed in the BScript console (if object CON exists). If box is set to 1, messages are displayed in a message box.

ABaseClass Member Functions

The ABaseClass class implements the following member functions. See CObj Member Functions for a list of functions implemented in the parent class.

setLog

Enable or disable logging to specified device or devices.

Usage:

inst SETLOG window{0|1} console{0|1} msgbox{0|1}

destruct

This function just calls the parent class' destruct function.

Usage:

inst destruct

setLogWindow

Enable or disable logging to the log window.

Usage:

inst setLogWindow 0|1

setLogConsole

Usage:

[inst] setLogConsole 0|1

Description:

Enable or disable logging to the console (CON).

setLogMsgbox

Usage:

[inst] setLogMsgbox 0|1

Description:

Enable or disable logging to message boxes.

AAxis : ABaseClass

AAxis is the abstract base class of all kinds of axes.

AAxis is derived from ABaseClass.

Member Variables

&name

The name of the axis (e.g. "time").

&parameter

The parameter this axis is part of.

&index

The index of this axis within the axes of its own kind in the parameter class.

AAxis Member Functions

The following member functions are supplied by AAxis. See ABaseClass Member Functions for a list of functions implemented in the parent class.

compare

Usage:

inst compare axis

Description:

Compares this axis with axis, returning 1 on equality and 0 otherwise.

compareConfiguration

Since AAxis is an abstract base class, there is no configuration and the function returns 1 if questionableConfigurationData is an empty string and 0 otherwise. Derived classes should compare the current configuration of this axis with the configuration specified by questionableConfigurationData.

Usage:

inst compareConfiguration unit refValue class

Result:

Returns 1 if they are identical or the same and 0 if they are not.

construct

Construct an AAxis instance. The first format expects arguments analogous to the classes member variables. The second format is intended for internal use only; it constructs the axis with the data shown at the current position in file.

Usage:

inst construct index name parameter

inst construct file [ parameter ]

Parameters:

index

The index of this axis within the axes of it's own kind.

name

The name of the axis (e.g. "time").

parameter

The parameter this axis is part of.

file

The file containing the axis data.

destruct

Usage:

inst destruct

Description:

Assign the parameter member variable an empty string and call the parent class' destruct function.

getCardinality

Usage:

inst getCardinality

Description:

Since AAxis is an abstract base class, this function returns an error message. Derived classes should return the cardinality of this axis, i.e. the number of values of this axis, or -1 in case of an infinite axis.

getCurrentConfiguration

Since AAxis is an abstract base class, this function returns an error message. Derived classes should return the current configuration of this axis. The current configuration is defined as all information necessary to convert axis data to a different configuration.

Usage:

inst getCurrentConfiguration

getIndex

Usage:

inst getIndex

Description:

Returns the index of this axis (e.g. "3").

getName

Usage:

inst getName

Description:

Returns the name of this axis (e.g. "time") .

getNativeValues

Usage:

inst getNativeValues [ axisArgs ] [ ; table ]

Description:

Since AAxis is an abstract base class, this function returns an error message. Please see the relevant derived class for details.

getNativeValuesForSegment

Usage:

inst getNativeValuesForSegment segmentIRef [ axisArgs ] [ ; table ]

Description:

Since AAxis is an abstract base class, this function returns an error message. Please see the relevant derived class for details.

getParameter

Usage:

inst getParameter

Description:

Returns the parameter this instance is being used by.

getUnit

Usage:

inst getUnit

Result:

Returns an error.

Description:

Since AAxis is an abstract base class, this function returns an error message. Derived classes should return the return the unit of this axis, e.g. "ms" for a time-axis.

Note, however, that it is legal for derived classes not to have a unit at all (e.g. AOrderAxis).

getValue

Usage:

inst getValue index

Description:

Returns the n-th value of this axis, n ranging from 0 (inclusive). This is a simple default implementation that should be overloaded for performance reasons.

getValues

Usage:

inst getValues [count [table]]

Description:

Since AAxis is an abstract base class, this function returns an error message. Please see the relevant derived class for details.

isDependent

Usage:

inst isDependent

Result:

Returns 0.

Description:

Since AAxis is an abstract base class, this function returns an error message. Derived classes should return truth if this axis is a dependent axis, falsehood otherwise.

isIndependent

Usage:

inst isIndependent

Result:

Returns 1.

Description:

Since AAxis is an abstract base class, this function returns an error message. Derived classes should return truth if this axis is an independent axis, falsehood otherwise.

loadAttributes

Usage:

inst loadAttributes file

Description:

Since AAxis is an abstract base class, this function does very little. It requires the parameter file, validates the XML in file and saves the value of the attribute ID in the class variable &name. Derived classes should require that the selected element in file describes an axis and load any appropriate attributes.

save

Usage:

inst save file [ position ]

Description:

Saves this axis in file at position or, if no position is supplied, at the current position. After completing successfully, the file position will be restored to whereever was before the save function was called.

saveAttributes

Usage:

inst saveAttributes file

Description:

Since AAxis is an abstract base class, this function does nothing. Derived classes should save all the appropriate attributes of this axis; the function requires file to be positioned to the element describing this axis. This function must be overloaded by axes having any appropriate attributes.

setCurrentConfiguration

Since AAxis is an abstract base class, this function returns an error message. Derived classes should set the configuration of this axis to configurationData, configuration being defined as all information necessary to convert axis data to a different configuration.

Usage:

inst setCurrentConfiguration configurationData

setIndex

Usage:

inst SETINDEX index

Description:

Sets the index of this axis.

setNativeValues

Usage:

inst setNativeValues [ axisArgs ] ; table

inst setNativeValues [ axisArgs ] ; value1 ...

Description:

Since AAxis is an abstract base class, this function returns an error message. Please see the relevant derived class for details.

setParameter

Usage:

inst setParameter parameter

Description:

Sets the parameter this axis is part of.

setValue

Usage:

inst setValue ?

Description:

Since AAxis is an abstract base class, this function returns an error message. Derived classes would set the n-th value. However, most classes will not supply this functionality.

setValues

Usage:

inst setValues val1 [ ...]

inst setValues table

Description:

Since AAxis is an abstract base class, this function returns an error message. Derived classes would set the first n values. However, most classes will not supply this functionality.

AOrderAxis : AAxis

This AOrderAxis class implements an independent, domain-less and unit-less order axis with a known cardinality. The only necessary parameter for creating an AOrderAxis is, therefore, the cardinality. The table entry of the ADesc static function SimpleNew would look like this:

$#tab * 'AOrderAxis Order 20'

The AOrderAxis class has no configurable attributes and therefore the member functions getCurrentConfiguration and setCurrentConfiguration do nothing.

You can retrieve all values in the axis with the following code:

#axis := $#par getIndependentAxis Order

1. values := $#axis getNativeValues

showtable $#values Values of the independent axis "Order" delete $#values

Member Variables

&cardinality

The cardinality of this axis or -1 indicating infinity.

See AAxis for additional member variables.

AOrderAxis Member Functions

The following member functions are supplied by AOrderAxis. See AAxis Member Functions for a list of functions implemented in the parent class.

compareConfiguration

Usage:

inst compareConfiguration questionableConfigurationData

Result:

Returns 1 if questionableConfigurationData is not an empty string.

Description:

AOrderAxis does not contain configuration data, so this function is of no use.

construct

Usage:

inst construct file [ parameter ]

inst construct index name parameter cardinality

Parameters:

cardinality

The cardinality of this axis or -1 indicating infinity.

See AAxis::construct for descriptions of the other parameters.

Description:

Constructs a new AOrderAxis instance.

destruct

Usage:

inst destruct

Description:

This function just calls AAxis::destruct.

getCardinality

Usage:

inst getCardinality

Result:

Returns the integer cardinality of the axis.

Description:

Get the value of the member variable &cardinality.

getCurrentConfiguration

The AOrderAxis class does not allow axis conversion and therefore this function does nothing.

Usage:

inst getCurrentConfiguration

Result:

Returns an empty string.

getUnit

Usage:

inst getUnit

Result:

Returns an empty string.

Description:

AOrderAxis has no unit.

getValue

Usage:

inst getValue index

Parameters:

index

An zero-based integer index (0 <= index).

Result:

Returns the value of index if index is within the bounds of the axis.

Description:

Returns the n-th value of this axis.

getValues

Usage:

inst getValues [ count [ table ] ]

Parameters:

count

The number of values to return. count must be a number greater than or equal to zero and less than the instance's cardinality. If count is not supplied, the value of the cardinality is used instead.

table

The id of a simple table. If no table is specified, a new table is created. This should then be deleted by the caller once it is no longer needed.

Result:

Returns a table containing one value per table row.

Description:

Fill a table with a list of count consecutive values starting from 0.

isDependant

Usage:

inst isDependent

Result:

Returns 0.

Description:

Returns false, since an order axis is never dependent.

setCurrentConfiguration

The AOrderAxis does not convert it's axis, therefore setCurrentConfiguration does nothing.

Usage:

inst setCurrentConfiguration configurationData

Result:

Returns an empty string.

setValue

Usage:

inst setValue

Description:

Outputs an error.

APlainAxis : AAxis

This class is the model of a plain, usual, standard axis, i.e. an axis with the following properties: domain, unit, reference value, and class.

Note that by default a plain axis is considered independent. If you want to derive a dependent axis from APlainAxis, you will have to overload the functions "isDependent" and "isIndependent".

Member Variables

&domain

The domain of this axis (e.g. "time" or "frequency").

&unit

The unit of this axis (e.g. "ms" or "kHz").

&refValue

The value based upon which the values of this axis have been calculated, if applicable.

&class

The "class" of this axis, showing how its values have been calculated (e.g. "lin" (linear) or "dB").

See AAxis for additional member variables.

APlainAxis Member Functions

The following member functions are supplied by APlainAxis. See AAxis Member Functions for a list of functions implemented in the parent class.

compareConfiguration

Usage:

inst compareConfiguration [ configData ]

Parameters:

configData

The configuration to compare. This must be in the following format:

unit refValue class

Note that if configData is empty, the configuration data is assumed to be identical!

Result:

Returns 1 if configData is identical to the instance's configuration and 0 if they are not.

Description:

Compare this instances configuration with configData returning 1 if they are the same or configData is not specified.

construct

Usage:

inst construct file [ parameter ]

inst construct index name parameter domain unit [ refValue [ class ] ]

Parameters:

See the member variables for a description of the class specific parameters.

See AAxis::construct for descriptions of the other parameters.

Description:

Constructs a new APlainAxis instance.

destruct

Usage:

inst destruct

Description:

This function just calls AAxis::destruct.

getClass

Usage:

inst getClass

Result:

Returns the value of &class.

Description:

Returns the class for this axis.

getCurrentConfiguration

Usage:

inst getCurrentConfiguration

Result:

Returns the configuration data in the following format:

unit refValue class

Description:

Returns the current configuration of this axis. The current configuration is defined as all the information necessary to convert axis data to a different configuration. In this class, this information is the unit, the reference value and class.

getDomain

Returns the domain for this axis.

Usage:

inst getDomain

Result:

Returns the value of &domain.

getRefValue

Usage:

inst getRefValue

Result:

Returns the value of &refValue.

Description:

Returns the reference value for this axis.

getUnit

Usage:

inst getUnit

Result:

Returns the value of &unit.

Description:

Returns the unit for this axis.

isDependent

Usage:

inst isDependent

Result:

Returns 0.

Description:

Returns false.

isIndependent

Usage:

inst isIndependent

Result:

Returns 1.

Description:

Returns true.

APlainCardinalityAxis : APlainAxis

This class is the model of a plain, usual, standard axis with a predefined cardinality.

Member Variables

&cardinality

The cardinality of this axis or -1 indicating infinity.

See APlainAxis for additional member variables.

APlainCardinalityAxis Member Functions

The following member functions are supplied by APlainCardinalityAxis. See APlainAxis Member Functions for a list of functions implemented in the parent class.

construct

Usage:

inst construct file [ parameter ]

inst construct index name parameter cardinality domain unit [ refValue [ class ] ]

Parameters:

See the member variables for a description of the cardinality parameter.

See APlainAxis::construct for descriptions of the other parameters.

Description:

Constructs a new APlainCardinalityAxis instance.

destruct

Usage:

inst destruct

Description:

This function just calls APlainAxis::destruct.

getCardinality

Usage:

inst getCardinality

Result:

Returns the integer cardinality of the axis.

Description:

Get the value of the member variable &cardinality.

AIncrementAxis : APlainCardinalityAxis

AIncrementAxis implements an increment axis, i.e. an axis where the first value is a specific number (the "start value") and each further value is an increment thereof as defined by the constant increment value. An AIncrementAxis has a known cardinality, a unit and a domain. The axis can also have a reference value, depending on the domain and unit.

An AIncrementAxis needs the cardinality, start value, increment value, domain and unit on creation. The following code example adds an AIncrementAxis entry to the table parameter of the ADesc static function SimpleNew:

$#tab * 'AIncrementAxis Time 10 0 2 time ms'

The above examples will create an axis with the following values: 0, 2, 4, 6, 8, 10, 12, 14, 16 and 18.

AIncrementAxis Attributes

Two AIncrementAxis attributes are configurable, the unit and the reference value. The function setCurrentConfiguration can be used for this purpose.

AIncrementAxis Native Values and Conversions

You can retrieve the values from the axis whilst converting on the fly with the function getNativeValues. The following example returns a table with second values from an increment axis with internal values in milliseconds:

#axis := $#par getIndependentAxis time

1. values := $#axis getNativeValues s

showitem $#values Values for the independent axis "time" in seconds delete $#values

Member Variables

&start

The start value of this axis.

&increment

The increment (may be any positive number > 0).

See APlainCardinalityAxis for additional member variables.

AIncrementAxis Member Functions

The following member functions are supplied by AIncrementAxis. See APlainCardinalityAxis Member Functions for a list of functions implemented in the parent class.

compareConfiguration

Usage:

inst compareConfiguration [ configData ]

Parameters:

configData

The configuration to compare. This must be in the following format:

unit refValue class

Note that if configData is empty, the configuration data is assumed to be identical!

Result:

Returns 1 if configData is identical to the instance's configuration and 0 if they are not.

Description:

Compare this instances configuration with configData returning 1 if they are the same or configData is not specified.

construct

Usage:

inst CONSTRUCT index name parameter cardinality start increment domain unit [ refValue [ class ] ]

inst CONSTRUCT file [ parameter ]

Parameters:

start

The first axis value. This must be number.

increment

The increment to add to start for every n+1 axis values. This may be any positive number except zero.

See APlainCardinalityAxis::construct for descriptions of the other parameters.

Result:

Returns 0 on success.

Description:

Construct an AIncrementAxis instance.

destruct

Usage:

inst destruct

Description:

This function just calls APlainCardinalityAxis::destruct.

getClass

Usage:

inst getClass

Result:

Returns the value of &class.

Description:

Returns the class for this axis.

getCurrentConfiguration

Usage:

inst getCurrentConfiguration

Result:

Returns the configuration data in the following format:

unit refValue class

Description:

Returns the current configuration of this axis. The current configuration is defined as all the information necessary to convert axis data to a different configuration. In this class, this information is the unit, the reference value and class.

getDomain

Returns the domain for this axis.

Usage:

inst getDomain

Result:

Returns the value of &domain.

getNativeValues

Return a table of the axis values converted using the specified parameters. This does not modify the internal axis values.

Usage:

inst getNativeValues [ unit [ refValue [ class ]]] [ ; table ]

Parameters:

unit

The unit to convert to. If unit is not specified, then &unit is used instead.

refValue

The reference value. If refValue is not specified, then &refValue is used instead.

class

The class. If class is not specified, then &class is used instead.

table

An optional table to store the axis values in. If no table is specified, a parameter table is created. See getValues for details.

Result:

Returns a table with the converted axis values.

getRefValue

Usage:

inst getRefValue

Result:

Returns the value of &refValue.

Description:

Returns the reference value for this axis.

getUnit

Usage:

inst getUnit

Result:

Returns the value of &unit.

Description:

Returns the unit for this axis.

getValue

Usage:

inst getValue [ index ]

Parameters:

index

An zero-based integer index (0 <= index < &cardinality). The default is 0.

Result:

Returns the value of index if index is within the bounds of the axis.

Description:

Returns the n-th value of this axis.

getValues

Usage:

inst getValues [ table | n | n table | table n ]

Parameters:

table

A parameter or a simple table. If no table is specified, getValues creates a parameter table with one field (val). The values are stored in the first column. Note that the old contents of the table are deleted before the requested values are added.

n

The number of axis values to return (starting from &start). n must be an integer greater than 0.

Result:

If successful, getValues returns a table where the first column contains the requested range of values.

Description:

Return the requested range of axis values in a table. If no parameters are passed, then all axis values are returned, unless the axis is infinite (&cardinality == -1), since this would take forever.

setCurrentConfiguration

Convert the axis data from the current unit to unit. Conversion takes refValue and class into account, if they are specified. If successful, the member variables &unit, &refValue and &class are set to the new configuration values. Note that this function converts the start and increment values as well.

Usage:

inst setCurrentConfiguration unit [ refValue [ class ]]

Result:

Returns an empty string if successful.

AEnumerationAxis : APlainCardinalityAxis

The AEnumerationAxis class implements an independent axis with a known number of values supplied by the user. The AEnumerationAxis axis has both a unit and a domain.

When creating an enumeration axis, you must specify the domain, unit, reference value (or null), the

Member Variables

&values

The table of values.

&storage

The file name *extension* for binary storage (if not set, data is being stored in-place).

&section

The section number for binary storage (Not used if &storage is not set).

See APlainCardinalityAxis for additional member variables.

AEnumerationAxis Member Functions

The following member functions are supplied by AEnumerationAxis. See APlainCardinalityAxis Member Functions for a list of functions implemented in the parent class.

compareConfiguration

Usage:

inst compareConfiguration [ configData ]

Parameters:

configData

The configuration to compare. This must be in the following format:

unit refValue class

Note that if configData is empty, the configuration data is assumed to be identical!

Result:

Returns 1 if configData is identical to the instance's configuration and 0 if they are not.

Description:

Compare this instances configuration with configData returning 1 if they are the same or configData is not specified.

construct

Usage:

inst CONSTRUCT index name parameter domain unit refValue class table|values

inst CONSTRUCT file [ parameter ]

Parameters:

domain

The axis domain (e.g. 'time' or 'frequency') compatible with the parameter parameter.

unit

The axis domain unit of measurement (e.g. 'ms') compatible with the parameter parameter.

refValue

The reference value.

class

The axis class (e.g. 'lin' or 'db') compatible with the parameter parameter..

table

A parameter table with one column containing the enumeration values.

values

A blank separated list of numerical values.

See AOrderAxis::construct for descriptions of the other parameters.

Result:

Returns 0 on success.

Description:

Construct an AEnumerationAxis instance.

destruct

Usage:

inst destruct

Description:

Deletes the &values table and calls AOrderAxis::destruct.

getClass

Usage:

inst getClass

Result:

Returns the value of &class.

Description:

Returns the class for this axis.

getCurrentConfiguration

Usage:

inst getCurrentConfiguration

Result:

Returns the configuration data in the following format:

unit refValue class

Description:

Returns the current configuration of this axis. The current configuration is defined as all the information necessary to convert axis data to a different configuration. In this class, this information is the unit, the reference value and class.

getDomain

Returns the domain for this axis.

Usage:

inst getDomain

Result:

Returns the value of &domain.

getNativeValues

Return a table of the axis values converted using the specified parameters. This does not modify the internal axis values.

Usage:

inst getNativeValues [ unit [ refValue [ class ]]] [ ; table ]

Parameters:

unit

The unit to convert to. If unit is not specified, then &unit is used instead.

refValue

The reference value. If refValue is not specified, then &refValue is used instead.

class

The class. If class is not specified, then &class is used instead.

table

An optional table to store the axis values in. If no table is specified, a parameter table is created. See getValues for details.

Result:

Returns a table with the converted axis values.

getRefValue

Usage:

inst getRefValue

Result:

Returns the value of &refValue.

Description:

Returns the reference value for this axis.

getUnit

Usage:

inst getUnit

Result:

Returns the value of &unit.

Description:

Returns the unit for this axis.

getValue

Usage:

inst getValue [ index ]

Parameters:

index

An zero-based integer index (0 <= index < &cardinality). The default is 0.

Result:

Returns the value of index if index is within the bounds of the axis.

Description:

Returns the n-th value of this axis.

getValues

Usage:

inst getValues [ table | n | n table | table n ]

Parameters:

table

A parameter or a simple table. If no table is specified, getValues creates a parameter table with one field (val). The values are stored in the first column. Note that the old contents of the table are deleted before the requested values are added.

n

The number of axis values to return (starting from &start). n must be an integer greater than 0.

Result:

If successful, getValues returns a table where the first column contains the requested range of values.

Description:

Return the requested range of axis values in a table. If no parameters are passed, then all axis values are returned, unless the axis is infinite (&cardinality == -1), since this would take forever.

setCurrentConfiguration

Usage:

inst setCurrentConfiguration [ unit [ refValue [ class ]]]

Parameters:

See AEnumerationAxis::contruct for a description of the parameters.

Result:

Returns an empty string if successful.

Description:

Convert the axis data from the current unit to unit. Conversion takes refValue and class into account, if they are specified. If successful, the member variables &unit, &refValue and &class are set to the new configuration values.

setStorage

Usage:

inst setStorage extension [ ; section ]

Parameters:

extension

The extension to use for the binary file. Note that the binary file has the format:

dataSetName.extension

This parameter is mandatory.

section

The section number. This must be number. If no section is specified, then data is appended to the file.

Result:

Returns an empty string on success.

Description:

Set the binary file extension used for storage and the section to use for storage. If no section is specified, data is appended to the file.

ASegmentEnumerationAxis : AEnumerationAxis

This class implements an axis whose values are relative to a segment of an audio file and whose values the user supplies by enumerating them.

Member Variables

&segment

The IRef of the segment the values of this axis are relative to.

&offset

The start of the above segment (in seconds).

ASegmentEnumerationAxis Member Functions

The following member functions are supplied by ASegmentEnumerationAxis. See AEnumerationAxis Member Functions for a list of functions implemented in the parent class.

construct

usage: inst CONSTRUCT index name parameter segment domain unit refValue (table | values)

Usage:

inst CONSTRUCT index name parameter segment domain unit refValue class table|values

inst CONSTRUCT file [ parameter ]

Parameters:

domain

The axis domain (e.g. 'time' or 'frequency') compatible with the parameter parameter.

unit

The axis domain unit of measurement (e.g. 'ms') compatible with the parameter parameter.

refValue

The reference value.

class

The axis class (e.g. 'lin' or 'db') compatible with the parameter parameter..

table

A parameter table with one column containing the enumeration values.

values

A blank separated list of numerical values.

See AOrderAxis::construct for descriptions of the other parameters.

Result:

Returns 0 on success.

Description:

Construct an AEnumerationAxis instance.

ADependentAxis : AAxis

ADependentAxis implements a dependent axis.

Member Variables

&domain

The domain of this axis (e.g. 'time' or 'frequency').

&unit

The unit of this axis (e.g. "kilohours" or "microhertz").

&class

The class of this axis (e.g. "linear", "ln").

&refValue

The reference value of this axis.

&name

The name of the axis (e.g. "time").

&parameter

The parameter this axis is part of.

&index

The index of this axis within the axes of its own kind in the parameter class.

ADependentAxis Member Functions

The following member functions are supplied by ADependentAxis. See AAxis Member Functions for a list of functions implemented in the parent class.

construct

Usage:

inst construct file

inst construct index name parameter domain unit refValue class

Parameters:

domain

The domain of this axis (e.g. "time" or "frequency").

unit

The unit of this axis (e.g. "kilohours" or "microhertz").

refValue

The class of this axis (e.g. "linear", "ln").

class

The reference value of this axis.

See AAxis::construct for descriptions of the other parameters.

Description:

Construct an ADependentAxis instance.

isDependent

Usage:

inst isDependent

Result:

Returns 1.

setCurrentConfiguration

ADesc : ABaseClass

This class implements a general parameter. Derived classes may provide more efficient implementations for special kinds of parameters.

ADesc is derived from ABaseClass.

Member Variables

&name

The unique name of this parameter.

&indepAxes

A simple table containing the names of the independent axes.

&depAxes

A simple table containing the names of the dependent axes.

&values

A simple table containing values. In the future, this table may not be available if the axes are infinite or live data, both of which have, however, not yet been implemented.

&state

The state of the object:

1 ... constructed, but not yet usable

2 ... axes are set up

3 ... axes are being filled with data

4 ... object is fully usable (and may no longer be changed structurally)

&calculatedForIref

The IRef of the entity (audio file/segment) the parameter is calculated for.

&adescPos

The BDataSet position of the parameter description.

&asegPos

The BDataSet position of the segment this parameter is calculated for.

&date, &time

The date and time of creation or latest modification, whichever comes last.

&storage

The extension of the binary data storage. If binary storage is specified, data is stored in a binary formatted file with the name '$($BDataSet GetPath).$&storage'. If this is unset, data are not being saved in binary format, but inplace in the XML DataSet.

&section

The section number in the binary file. If this is set, it names the section where to store the data values of this parameter. If it isn't, data is being stored in a new section whose number is then stored in &section.

&card

The total cardinality (or -1 for infinite or 0 for undefined cardinality), being defined as the number of values per dependent axis

&attributes

An extended table containing the names and values of the user-defined attributes in the fields name and value.

&converter

The converter class, an instance of the ADescConverter class. This is a strong reference.

ADesc Member Functions

The following member functions are supplied by ADesc. See ABaseClass Member Functions for a list of functions implemented in the parent class.

construct

Construct an ADesc instance. The parameter data is either stored in a binary file or in the XML DataSet.

Usage:

inst construct name [ BINARY|XML [ aseg ] ] ; [ ; converter ]

Parameters:

name

The name to identify this ADesc instance with.

aseg

The IRef of the audio segment for which this parameter has been calculated.

converter

Either an ADescConverter instance, or the name of a class derived from ADescConverter. This converter is used for value conversions. The new ADesc instance takes ownership of the converter and is responsible for releasing it when it is destroyed. Noone else should use the converter except the owning instance.

destruct

Reset the parameter, destroy the converter and calls the parent's destruct function.

getAxis

Returns the first independent axis whose name is name or, if there is no such independent axis, the first dependent axis whose name is name.

Usage:

inst getAxis name

Parameters:

name

The name of an independent or dependent axis.

getConverter

Returns the value of the &converter member variable.

getDependentAxis

Returns the dependent axis identified by index or name.

Usage:

inst getDependentAxis index|name

Parameters:

index

The index of an existing dependent axis.

name

The name of an existing dependent axis.

Result:

An axis instance or an empty string.

getDependentAxesCount

Returns the number of dependent axes.

getIndependentAxesCount

Returns the number of independent axes.

getDependentAxisByName

Returns the first dependent axis identified by name.

Usage:

inst getDependentAxisByName name

Parameters:

name

The name of an existing dependent axis.

Result:

An axis instance or an empty string.

getDependentAxisIndexByName

Returns the lowest index of an existing dependent axis identified by name.

Usage:

inst getDependentAxisByName name

Parameters:

name

The name of an existing dependent axis.

Result:

Either lowest index of an axis with the name name, or -1 if no such axis exists.

getIndependentAxis

Returns the independent axis identified by index or name.

Usage:

inst getIndependentAxis index|name

Parameters:

index

The index of an existing independent axis.

name

The name of an existing independent axis.

Result:

An axis instance or an empty string.

getIndependentAxisByName

Returns the first independent axis identified by name.

Usage:

inst getIndependentAxisByName name

Parameters:

name

The name of an existing independent axis.

Result:

An axis instance or an empty string.

getIndependentAxisIndexByName

Returns the lowest index of an existing independent axis identified by name.

Usage:

inst getIndependentAxisByName name

Parameters:

name

The name of an existing independent axis.

Result:

Either lowest index of an axis with the name name, or -1 if no such axis exists.

getInternalValues

Returns the value of the &values member variable.

getState

Returns the value of the &state member variable.

setConverter

Sets the converter to use for this parameter. If a converter was previously defined, it is destroyed.

Usage:

inst setConverter converter

Parameters:

converter

Either an ADescConverter instance, or the name of a class derived from ADescConverter. This converter is used for value conversions. The new ADesc instance takes ownership of the converter and is responsible for releasing it when it is destroyed. Noone else should use the converter except the owning instance.

getUnit

Returns the unit of a specific dependent axis.

inst getUnit depIndex

Parameters:

depIndex

The index of an existing dependent axis.

getMinDepNum

Returns the minimum number of dependent axes this instance is allowed to have.

getMinIndepNum

Returns the minimum number of independent axes this instance is allowed to have.

getDependentAxes

Returns the value of the &depAxes member variable.

getIndependentAxes

Returns the value of the &indepAxes member variable.

compare

Compares this parameter with the parameter argument adesc.

Usage:

inst compare adesc

Parameters:

adesc

The name of an ADesc instance of an instance of a class derived from ADesc.

Result:

0 if the parameter values are different, 1 if they are the same.

addIndependentAxis

Add an independent axis instance to this instance.

Usage:

inst addIndependentAxis axis

Parameters:

axis

An instance of an axis class. Note that once added to a parameter, the axis instance cannot be used by any other parameter. The parameter destroys the axis instance when it is itself destroyed.

Result:

Returns the index of the successfully added axis, or an asterisk on error.

addDependentAxis

Add a dependent axis instance to this instance.

Usage:

inst addDependentAxis axis

Parameters:

axis

An instance of an axis class. Note that once added to a parameter, the axis instance cannot be used by any other parameter. The parameter destroys the axis instance when it is itself destroyed.

Result:

Returns the index of the successfully added axis, or an asterisk on error.

getCardinality

Returns the value of the &card member variable.

getValue

Returns the index-th dependent value at coordinates <a1,...,am>. <a1,...,am> may be supplied directly as a blank separated list or indirectly, as a table whose i-th entry specifies ai.

Usage:

inst getValue index coordinateList

inst getValue index table

Parameters:

index

The index of a value in the dependent axis. Indices are zero-based.

coordinateList

The blank separated list of axes coordinates. Coordinates are zero-based.

table

A table with one entry per coordinate.

Result:

The requested value or an asterisk on error.

Examples:

In a 3 dimensional coordinate space with the independent axes 'time' and 'frequency' and the dependent axis 'amplitude', the following command would get the amplitude at 1000Hz at the time 500ms:

#amp := $($#par getValue 0 500 1000)

setValue

Sets the dependent value with the index i at coordinates <a1,...,am> to a specific value. <a1,...,am> may be supplied directly as a blank separated list or indirectly, as a table whose i-th entry specifies ai.

Usage:

inst setValue depIndex value axisCoordinateList

inst setValue depIndex value table

Parameters:

depIndex

The zero-based index of the dependent axis in which the value should be set.

value

The value to set.

axisCoordinateList

A blank separated list of axis coordinates.

table

A table with one entry per axis coordinate.

setNativeValues

The function setNativeValues is not implemented for the general parameter class ADesc. Derived classes should implement a setNativeValues function if performance is an issue.

getNativeValues

The function getNativeValues is not implemented for the general parameter class ADesc. Derived classes should implement a getNativeValues function if performance is an issue.

Usage:

inst getNativeValues depIndex [ axisArgs ] [ ; table ]

inst getNativeValues depIndex [ axisArgs ]

getNativeValuesForSegment

The function getNativeValuesForSegment is not implemented for the general parameter class ADesc. Derived classes should implement a getNativeValuesForSegment function if performance is an issue.

If implemented, the function should gets those values for the dependent time axis indicated by index "depIndex" or called "name" which lie in the segment named by segment IRef "segmentiref". Otherwise, it works just like "getNativeValues", all other parameters being the same and having the same significance.

Usage:

inst getNativeValuesForSegment depIndex|name segmentiref [ axisArgs ] [ ; table ]

inst getNativeValuesForSegment depIndex|name segmentiref [ axisArgs ]

setValues

Sets all the values of the dependent axis identified by depIndex or name to the specified values. If the number of values specified is less than the number of value in the dependent axis, only the first values are set, the rest are left untouched.

Usage:

inst setValues depIndex|name values

inst setValues depIndex|name valueTable

Parameters:

depIndex

The zero-based index of the dependent axis to be modified.

name

The name of the dependent axis to be modified.

values

A blank separated list of values.

depIndex

A parameter or an extended table containing one value per entry.

valueTable

An extended or parameter table containing the values.

getValues

Returns all values for a specific dependent axis.

Usage:

inst getValues depIndex|name [ table ]

Parameters:

depIndex

The zero-based index of the dependent axis.

name

The name of the dependent axis.

table

A table to receive the dependent axis' values. Note that any existing content in the table is destroyed first. This can be either a parameter table or a simple table.

Result:

If table was specified, table is returned, otherwise a new parameter table is created and returned. One value is stored per entry.

dumpValues

Dumps all the dependent values to the log window.

Usage:

inst dumpValues

Result:

0

dumpValueVector

Dumps the value vector as one long string to the log window.

Usage:

inst dumpValueVector

Result:

0

getValueVector

Returns all the values of this parameter as a vector (i.e. one-dimensional table).

This function is probably is most useful for two-dimensional parameters (two axes, one independent, one dependent). In this case it directly returns the values of this parameter.

Note that there is no predefined order in which to arrange values. Derived classes may arrange values in their own fashion. You will need to call "getIndexForCoordinates" and "getCoordinatesForIndex" if you want to find out which particular index corresponds to which coordinate (and vice versa).

See Vector Format below for a description of the vector format in this class.

Usage:

inst getValueVector [ table ]

Parameters:

table

The target table (simple or parameter) for the values.

Result:

If table was specified, table is returned, otherwise a new parameter table is created and returned. One value is stored per entry.

Vector Format:

For parameters with more than one independent axis, this function returns the values with the index of the first dimension varying most slowly and the index of the last dimension varying fastest. In addition, if there is more than one dependent axis, for each coordinate <a1,...,am> (m being the number of independent axes), the values of the dependent axes at <a1,...,am> are added to the table one after the other.

setValueVector

Sets all the values of this parameter to those specified in the supplied value vector. The format of this value vector is described for the getValueVector function.

Usage:

inst setValueVector [ table ]

Parameters:

table

A one dimensional table containing the values to set. See getValueVector for a description of the vector format.

getIndexForCoordinates

Returns the index of a dependent axis value within a vector as returned by getValueVector.

Usage:

inst getIndexForCoordinates depIndex table

inst getIndexForCoordinates depIndex coordinateList

Parameters:

depIndex

The zero-based dependent axis index.

table

A table with one coordinate per entry.

coordinateList

A blank separated list of coordinates.

getCoordinatesForIndex

Calculates the coordinates of the value that is stored in the index-th element of the value vector as returned by getValueVector.

Usage:

inst getCoordinatesForIndex index [ table ]

Parameters:

index

The index of the coordinates to retrieve.

table

A simple table to receive the results of the query.

Result:

A simple table containing the results of the query as one entry per coordinate. Note that the first entry is the index of the dependent parameter. If table was not supplied, a new table is created.

getValueMatrix

For three-dimensional parameters (i.e. parameters with exactly two independent axes), this function returns a c1 x c2 - matrix, c1 being the cardinality of the first independent axis and c2 being the cardinality of the second independent axis, such that each element <a,b> of the matrix is the value of the parameter at coordinates <a,b>.

Usage:

inst getValueMatrix [ depIndex [ table ] ]

Parameters:

depIndex

The index of the dependent axis to retrieve the values of. This parameter is only necessary if there is more than one dependent axis.

table

If specified, values are stored in this table. Otherwise, a new table is created.

Result:

If table was specified, table is returned, otherwise a new parameter table is created and returned.

setValueMatrix

The setValueMatrix function is not implemented in the ADesc class and will return an error. Parameter classes which store matrices (e.g. ADesc2) should implement a setValueMatrix function.

replace

Replaces the parameter saved at "position" with the current parameter doing some superficial sanity checks.

Usage:

inst replace position

save

Save this parameter to its storage medium.

Usage:

inst save

removeFromDataset

This function removes the parameter from the XML file, more precisely: It removes all occurrence of like-named parameters in the segment this parameter has been calculated for from the file. It does no harm to the in-memory instance of the parameter, so you may continue using it (and you may at a later time save it again).

Usage:

inst removeFromDataset

Result:

The number of occurrences which were deleted.

setStorage

Sets the extension of the binary file and, optionally, the section number where to store data values. If no neither extension nor section number are specified, the data will be stored inplace in the XML file. If no section number is supplied, data is being appended to the binary file.

Note that you may use this function to switch between XML and binary storage even after the parameter has already been saved. By clearing the binary file name (i.e. calling "setStorage" with an empty file name), you force the next save operation to take place in XML format. With setting a binary file name, you force the next save operation to save the data in binary format. Also note that the semicolon is required because filenames may contain all kinds of whitespace characters.

Usage:

inst setStorage [ extension [ ; section ]]

Parameters:

extension

The string to use as the binary file extension (e.g. 'dat'). The base file name is the same as the DataSet filename (e.g. if the DataSet is the default 'stxdataset.xml' and the extension is 'dat' then the binary file name will be 'stxdataset.xml.dat'. If setStorage is never called, then the default extension 'adesc' is used (e.g. 'stxdataset.xml.adesc').

section

The section number where data should be stored in the binary file. If this parameter is missing, data is simply appended to the file.

getStorage

Returns the value of the &storage member variable.

setAudio

Tells this parameter which audio segment it has been calculated for.

Usage:

inst setAudio aseg

Parameters:

aseg

An audio segment IRef in the current DataSet.

getAudio

Returns the value of the &asegPos member variable. This can be set with the function setAudio.

getCalculatedForIref

Returns the value of the &calculatedForIref member variable.

reset

Resets this parameter to empty.

Usage:

inst reset [ silentFlag ]

Parameters:

silentFlag

If 0, all local data structures are released, meaning that the parameter is no longer usable. If anything other than 0 (the default), the local data structures are re-initialized, meaning that the parameter is an empty parameter that may be used again.

setAttribute

Set one or more user defined attributes to a specific values.

Usage:

inst setAttribute name=value [ ; attributeList ]

Parameters:

name

An attribute name. This must be a valid string for an XML attribute.

value

Any string value.

attributeList

A semi-colon separated list of name=value pairs.

getAttribute

Get the value of an existing attribute.

Usage:

inst getAttribute name

Parameters:

name

The name of the attribute who's value you want to retrieve.

Result:

The value of the requested attribute or empty if the attribute does not exist or is empty.

getAttributes

Returns all user-defined attributes (in no particular order) in a table with two columns, "name" and "value", each entry containing the name of an attribute and its respective value.

Usage:

inst getAttributes

Result:

An extended table with two fields - name and value.

load

Loads the parameter from the named position.

Usage:

inst load iref

Parameters:

iref

The internal reference (IRef) of an audio segment and parameter to load (E.g. '/TestFile/TestSegment/Parameter1')

setCurrentConfiguration

Sets the configuration of the dependent axis named by index "depAxisIndex" to "configurationData", configuration being defined as all information necessary to convert axis data to a different configuration.

Usage:

inst setCurrentConfiguration depAxisIndex configData

Parameters:

depAxisIndex

The zero-based index of the axis to be configured.

configData

The configuration data for the axis. See the relevant axis setCurrentConfiguration function documentation for the format of the configuration data.

getCurrentConfiguration

Returns the current configuration of the dependent axis named by "depIndex"

Usage:

inst getCurrentConfiguration depAxisIndex

Parameters:

depAxisIndex

The zero-based index of an existing axis.

Result:

The configuration data as described in the getCurrentConfiguration documentation for the relevant axis.

ADesc Static Functions

The ADesc class supports the following static functions. These can be called without an instance.

GetSubSegmentData

Extract data for subsegment subaseg from all objects (tables) of the datalist. It is assumed, that the rows of each table are associated to equally spaced frames of the master segment aseg.

Usage:

ADESC GETSUBSEGMENTDATA aset; aseg; subaseg; datalist; delorig

Parameters:

aset

audio set

aseg

audio segment id of master segment

subaseg

audio segment id of subsegment

datalist

blank seperated list of data tables

delorig

delete original data tables after extraction

Result:

Blank separated list of extracted dataobjects (subdata1 subdata2 ..) or empty string.

GetSegmentInformation

Returns the start offset and the duration of the segment named by "iref", both measured in seconds (default) or, if so desired, in milliseconds.

Usage:

ADesc GETSEGMENTINFORMATION iref [ ; s|ms ]

GetReservedAttributes

Returns a blank separated list of attributes which are reserved by STx.

CheckReservedAttribute

Check if an attribute is reserved or not.

Usage:

ADesc CheckReservedAttribute attr

Result:

An asterisk if the attribute attr is reserved, otherwise an empty string.

GetBestClassForAxes

Returns the name of the class that is best suited for a parameter with "nIndependentAxes" independent and "nDependentAxes" dependent axes.

Usage:

ADesc GetBestClassForAxes nIndependentAxes [ nDependentAxes ]

Result:

Returns one of the following values:

ADesc

ADesc0

ADesc1

ADesc2

GetSuitability

This function tells the caller how well this class handles parameters with "indepCount" independent axes and "depCount" dependent axes whose cardinalities are the numbers stored in "depTable", -1 indicating an axis being infinite. If you don't specify "depTable", the function assumes all axes being finite.

Usage:

ADesc GetSuitability indepCount depCount [ depTable ]

Result:

The result is a number from 0 to 10 (inclusive), 0 indicating that this class cannot handle such a parameter, 10 indicating that this class loves to handle such a parameter, and 1-9 indicating suitabilities in between.

Load

Loads and initializes an ADesc parameter from "file". The exact type of parameter returned (e.g. ADesc, ADesc1 or ADesc2 etc) is determined by the XML attribute value stored in the file.

Usage:

ADesc Load iref

Parameters:

iref

The IRef of a parameter in the current DataSet (E.g. '/TestFile/Segment1/Param1').

Result:

If successful, this function returns a parameter initialized with the data from the file.

LoadData

Load data of specified axes from the specified ADesc element. If iref or name is specified a temporary ADesc object is created and deleted after loading has finished.

Usage:

ADESC LoadData adescobject ; merge ; axisname1 [unit1 ref1 class1]; ...

ADESC LoadData adesciref ; [adescname]; merge ; axisname1 [unit1 ref1 class1]; ...

Result:

Blank separated list of dataobjects (axisdata1 axisdata2 ..) or empty string; "*" (asterisk) on error; "aDescError" empty or set to an appropriate error message.

New

Create a new ADesc instance.

Usage:

Equivalent to SimpleNew. See SimpleNew for parameter details.

ADesc New name BINARY|XML indepTable depTable [ aseg ] [ ; converter ]

ADesc New name BINARY|XML table [ aseg ] [ ; converter ]

Equivalent to ComplexNew. See ComplexNew for parameter details.

ADesc New configTable ; parName ; storage ; iref ; save ; converter ; attributes

SimpleNew

Create a new parameter instance derived from ADesc. The exact type is chosen automatically using the function GetBestClassForAxes.

The keywords "BINARY" and "XML" specify how to store the data. XML means that they are being stored inplace in the STx XML DataSet (like the old APar class), BINARY means that they are stored in an external binary file. By default, the file name used for this file is generated automatically, and the file is placed in the STx directory, "$@root". You may change the name and location of this binary file by calling setStorage and supplying this function with the desired file name.

Usage:

ADesc SimpleNew name BINARY|XML indepTable depTable [ aseg ] [ ; converter ]

ADesc SimpleNew name BINARY|XML table [ aseg ] [ ; converter ]

Parameters:

name

The name of this parameter.

indepTable

The name of the table specifying the independent axes.

depTable

The name of the table specifying dependent axes.

table

The name of the table specifying both dependent and independent axes. All independent axes must be stored before the dependent axes.

aseg

The IRef of the segment this parameter has been calculated for.

converter

Either an ADescConverter instance, or the name of a class derived from ADescConverter. This converter is used for value conversions. The new ADesc instance takes ownership of the converter and is responsible for releasing it when it is destroyed. Noone else should use the converter except the owning instance.

Table Entry Format

The table entries can be any one of the following:

AOrderAxis Name [arguments]

AIncrementAxis Name [arguments]

AEnumerationAxis Name [arguments]

ASegmentEnumerationAxis Name [arguments]

ASegmentIncrementAxis Name [arguments]

ADependentAxis Name [arguments]

See the individual axis documentation for argument details.

Examples:

Create a new parameter instance. Exactly which class is chosen (e.g. ADesc1 or ADesc2 etc) is left to the ADesc New static function.

#tab := new table *
//          class               name            axis arguments
$#tab *     'AIncrementAxis     time            30 0 1 time s'  // card. start incr. domain unit
$#tab *     'ADependentAxis     frequency       frequency Hz'   // domain unit
$#tab *     'ADependentAxis     amplitude       amplitude dB 1' // domain unit ref.value

//          name        storage     setup   audio file
#par := ADesc new   example1    xml     $#tab   /MyWave/Segment1
if '~$#par' != instance then
    writelog 'Error when initializing ADesc1: $aDescError'
    exit
end
writelog '==> automatically selected class $#par[!CLASS]'

delete $#tab

ExtNew

Create a new ADesc instance.

Usage:

Equivalent to SimpleExtNew. See SimpleExtNew for parameter details.

ADesc ExtNew class name BINARY|XML indepTable depTable [ aseg ] [ ; converter ]

ADesc ExtNew class name BINARY|XML table [ aseg ] [ ; converter ]

Equivalent to ComplexExtNew. See ComplexExtNew for parameter details.

ADesc ExtNew class ; configTable ; parName ; storage ; iref ; save ; converter ; attributes

SimpleExtNew

The keywords "BINARY" and "XML" specify how to store the data. XML means that they are being stored inplace in the STx XML DataSet(like the old APar class), BINARY means that they are stored in an external binary file. By default, the filename used for this file is generated automatically, and the file is placed in the STx directory, "$@root". You may change the name and location of this binary file by calling "setStorage" and supplying this function with the desired filename.

Usage:

ADesc SimpleExtNew class name BINARY|XML indepTable depTable [ aseg ] [ ; converter ]

ADesc SimpleExtNew class name BINARY|XML table [ aseg ] [ ; converter ]

Parameters:

class

The name of the class to instantiate. It must be derived from ADesc.

See SimpleNew for a description of the other parameters.

ComplexNew

Create a new parameter instance derived from ADesc. The exact type is chosen automatically using the function GetBestClassForAxes. You can use both the configuration table configTable and the other command parameters to configure the instance. You do not need to specify both.

Usage:

ADesc ComplexNew configTable ; parName ; storage ; iref ; save ; converter ; attributes

Parameters:

configTable

A simple table with one entry per configuration command. Each entry must start with one of the following commands:

STORAGE | IREF | NAME | AXIS | ATTRIBUTE | SAVE

See Configuration Table Settings below for details.

parName

The name of the parameter to store.

storage

One of the following two values:

XML|BINARY

If this parameter is not specified, a binary file is used.

iref

The IRef of the audio segment for which the parameter has been calculated.

save

If set to 1, the parameter is immediately saved and the instance is destroyed and this function returns an empty string. Otherwise, this fu

converter

Either an ADescConverter instance, or the name of a class derived from ADescConverter. This converter is used for value conversions. The new ADesc instance takes ownership of the converter and is responsible for releasing it when it is destroyed. Noone else should use the converter except the owning instance.

attributes

If supplied,, user-defined attributes are to be set for the parameter.

Result:

The name of a parameter instance, an empty string (if the parameter 'saved' - see save for details) or an error (an asterisk).

Configuration Table Settings

STORAGE BINARY|XML|DEFAULT

Sets the storage class of the parameter. If you supply a storage class both as an argument to this function and as an entry in the configuration table, strange things may happen.

IREF iref

This configuration command informs the parameter which audio segment it has been calculated for. Please use either this parameter or the ComplexNew parameter iref, not both.

AXIS name type axisargs

This configuration command informs the parameter that it has an axis called name of the type kind. The type kind currently is one of the words Order, Increment, Enumeration, SegmentEnumeration, or Dependent. The class name of the respective axis class is directly derived from the supplied type kind by prefixing it with the string "A" and suffixing it with the string "Axis". Please make sure that the resulting string is a class name and, more specifically, the name of a class derived from AAxis. It may even be a user-supplied class derived from AAxis. axisargs depend on the type of axis being configured.

ATTRIBUTE name value

By providing entries of this kind, you may set user-defined attributes for this parameter even at this early stage. Of course, you may at any later stage call setattribute.

SAVE

By providing this keyword, you are asking the function to save the parameter immediately and eliminate it from memory. This is the same as providing the string "1" for the save argument of this function.

ComplexExtNew

Create a new parameter instance of a specific type of ADesc parameter. Any class derived from ADesc can be instantiated.

Usage:

ADesc ComplexExtNew adescClass ; configTable ; parName ; storage ; iref ; save ; converter ; attributes

Parameters:

adescClass

The name of a class derived from ADesc or ADesc itself. This type of parameter will be instantiated.

See ComplexNew for a description of the other parameters.

RemoveFromDataset

Remove all occurrences of parameters named adescName from the segment segmentIRef.

Usage:

ADesc RemoveFromDataset segmentIRef adescName

Result:

The number of occurrences which were removed.

ADesc1 : ADesc

The ADesc1 class is made for efficiently storing and handling parameters with exactly one independent axis. Preferred means of access are the member functions "getValues", "setValues", "getValue" and "setValue". Neither "getValueMatrix" nor "setValueMatrix" functions defined in the parent class are supported because there is no matrix where there is only one independent axis. "getValueVector" and "setValueVector" are supported and work as usual, but they are slow compared to "getValues" and "setValues" and, hence, should not be excessively used.

The class ADesc1 is derived from the class ADesc.

Member Variables

The class ADesc1 does not implement any additional member variables. However, the content of the &values member variable is different from that of the ADesc class.

&values

A simple table containing values. In the future, this table may not be available if the axes are infinite or live data, both of which have, however, not yet been implemented.

ADesc1 Member Functions

The following member functions are supplied by ADesc1. See ADesc Member Functions and ADesc Static Functions for a list of functions implemented in the parent class.

setNativeValues

This function sets the values for the dependent axis identified by the index "depIndex". It does so in the most natural way of this axis, e.g. using a vector in the one-dimensional case or using a matrix in the two-dimensional case, leaving the definition of "most natural" and the details of implementation to the respective concrete class.

Usage:

inst setNativeValues depIndex [ axisArgs ] ; table

inst setNativeValues depIndex [ axisArgs ] ; value1 ...

addIndependentAxis

Add an independent axis instance to this instance.

Usage:

inst addIndependentAxis axis

Parameters:

axis

An instance of an axis class. Note that once added to a parameter, the axis instance cannot be used by any other parameter. The parameter destroys the axis instance when it is itself destroyed.

Result:

Returns the index of the successfully added axis, or an asterisk on error.

Notes:

You can only call this function once for any ADesc1 instance.

addDependentAxis

Add a dependent axis instance to this instance.

Usage:

inst addDependentAxis axis

Parameters:

axis

An instance of an axis class. Note that once added to a parameter, the axis instance cannot be used by any other parameter. The parameter destroys the axis instance when it is itself destroyed.

Result:

Returns the index of the successfully added axis, or an asterisk on error.

Notes:

You can only call this function once for any ADesc1 instance.

setValue

Sets the dependent axis (value with the index i at a specific axis coordinate.

Usage:

inst setValue depIndex value axisCoordinate|table

Parameters:

depIndex

The zero-based index of the dependent axis in which to set the value (E.g. if there are two dependent axis, this value can be 0 or 1).

value

The value to set.

axisCoordinate

The independent axis coordinate (E.g. for an independent axis with 10 values, any value from 0 to 9).

table

A table with one entry containing the coordinate (see axisCoordinate for details).

getValue

Get a dependent axis value at a specific independent axis coordinate.

Usage:

inst getValue depIndex indepCoord|table

Parameters:

depIndex

The zero-based index of the dependent axis from which to retrieve the value (E.g. if there are two dependent axis, this value can be 0 or 1).

indepCoord

The independent axis coordinate (E.g. for an independent axis with 10 values, any value from 0 to 9) from which to retrieve the value.

table

A table with one entry containing the coordinate (see indepCoord for details).

Examples:

For a parameter with one two dependent axes (frequency and amplitude) and one independent axis (time), the following command would get the amplitude value at 10 seconds (assuming the time axis is an incremental axis starting at 0 with an incremental step of 1 second):

$#par getValue 1 9

getValueVector

Returns all values in this parameter as a one-dimensional parameter table.

Usage:

inst getValueVector [ table ]

Parameters:

table

A parameter table to receive the values. If this is not specified a parameter table is created.

Result:

If table was specified, table is returned, otherwise a new parameter table is created and returned. One value is stored per entry.

Vector Format

The table contains one value per entry.

setValueVector

Sets all the values of this parameter to those specified in the supplied value vector. The format of this value vector is described for the getValueVector function.

Usage:

inst setValueVector [ table ]

Parameters:

table

A one dimensional table containing the values to set. See getValueVector for a description of the vector format.

getValues

Returns all values for a specific dependent axis. Note that it is more desirable not to supply a table argument (performance hit of c. 25%).

Usage:

inst getValues depIndex|name [ table ]

Parameters:

depIndex

The zero-based index of the dependent axis.

name

The name of the dependent axis.

table

A parameter table to receive the dependent axis' values. Note that any existing content in the table is destroyed first.

Result:

If table was specified, table is returned, otherwise a new parameter table is created and returned. One value is stored per entry.

setValues

Sets all the values of the dependent axis identified by depIndex or name to the specified values. If the number of values specified is less than the number of value in the dependent axis, only the first values are set, the rest are left untouched.

Usage:

inst setValues depIndex|name values

inst setValues depIndex|name valueTable

Parameters:

depIndex

The zero-based index of the dependent axis to be modified.

name

The name of the dependent axis to be modified.

values

A blank separated list of values.

depIndex

A parameter or an extended table containing one value per entry.

valueTable

A parameter table with one column containing the values.

ADescConverter : ABaseClass

ADescConverter Member Functions

The following member functions are supplied by ADescConverter. See ABaseClass Member Functions for a list of functions implemented in the parent class.

construct

Construct a new ADescConverter instance.

Usage:

inst construct parameter

Parameters:

parameter

The parameter to associate with this ADescConverter instance.

Result:

0 on success, 1 on failure.

destruct

Clean up this instance.

setParameter

Associate a new parameter instance with this ADescConverter instance.

Usage:

inst setParameter parameter

Parameters:

parameter

The parameter to associate with this ADescConverter instance.

checkAxisName

Check the validity of a string is an axis 'name'.

Usage:

inst checkAxisName name

Parameters:

name

The string whose validity is to be checked.

checkParameterName

Check the validity of a string is a parameter 'name'.

Usage:

inst checkParameterName name

Parameters:

name

The string whose validity is to be checked.

LazyUnitOrDomainCheck

Performs a superficial check for the validity of "unitOrDomain" as a unit or a domain. ;Superficial' means that it only checks "unitOrDomain" for invalid characters. The function returns the empty word on success.

Usage:

inst LazyUnitOrDomainCheck unitOrDomain

Parameters:

unitOrDomain

The unit or domain to check for invalid characters.

Result:

An empty string on success.

getDomains

Returns a simple table with one entry per valid domain. Valid domains are those supported by this class. Derived classes can implement additional domains.

Usage:

inst getDomains

Result:

A simple table containing a list of valid domains - one entry per valid domain.

checkDomain

Check if a domain is a valid (conversion is supported) or not.

Usage:

inst checkDomain domain

Parameters:

domain

The domain to check.

Result:

An empty string on success.