Tag Status and Manipulation

About the Tag Status and Manipulation Methods

The tag status and manipulation methods are used to read in values of the COF (Control Object File) file's tags or write values to the tags themselves.

Tag Status Methods

Tag Manipulation Methods

GetTagVal

Returns the value of a specified parameter tag. Because parameter tags point to a parameter input or output, GetTagVal provides a means of determining the current value of a parameter. It can be used with all parameter types and returns a single floating point value.

float GetTagVal(string Name)

Arguments:

Type	Argument	Description
string	Name	A string variable that matches exactly the name of a parameter tag.

Returns:

Type	Value	Description
float	current value of tag	The numerical type of the parameter does not affect the return variable.

Reads value of tag labeled 'RMS' and saves it to the variable rms.

MATLABPython

rms = RP.GetTagVal('RMS'); % Reads rms level

rms = RP.GetTagVal('RMS')  # Reads rms level

See also: Band-limited Noise, Continuous Play, Continuous Acquire, and Two Channel Continuous Acquire in the ActiveX examples.

GetTagType

Determines the data type of a parameter tag.

int GetTagType(string Name)

Arguments:

Type	Argument	Description
string	Name	The name of a parameter tag.

Returns:

Type	Value	Description
MATLAB	int	An Integer that maps to an ASCII character.
Data Type	Integer Value
Data Buffer	68
Integer	73
Logical (1 or 0)	78
Float(Single)	83
Coefficient Buffer	80
Undefined (e.g. latch output)	65
Data Type	Ascii Map
Data Buffer	"D"
Integer	"I"
Logical (1 or 0)	"L"
Float(Single)	"S"
Coefficient Buffer	"P"
Undefined (e.g. latch output)	"A"

Finds the data type of a particular parameter tag.

MATLAB

DataType = char(RP.GetTagType('RAMBuffer'));

See also: Device Checker in the ActiveX examples.

GetTagSize

Returns the maximum number of data points accessible through the parameter tag.

int GetTagSize(string Name)

Arguments:

Type	Argument	Description
string	Name	A string variable that matches the name of a parameter tag.

Returns:

Type	Value	Description
int	0= error, 1=Logic, Integer, Float (Single),>1 Data type (a buffer).

Returns the number of points in the ram buffer.

MATLAB

Tagsize = RP.GetTagSize('RAMBuffer');

See also: Device Checker in the ActiveX examples.

ReadTag

Reads data from the processor device's memory into variables stored on the PC. ReadTagV should be used with MATLAB. Other programming languages should use ReadTag. See ReadTagVEX for alternative ways to read data.

ReadTag can be used with any component that has a data buffer, such as: RamBuffer, LongDynDel, FIR and so forth.

int ReadTag(string Name, float[] pBuf, int nOS, int nWords);

Arguments:

Type	Argument	Description
string	Name	Name of parameter tag.
float[]	pBuf	Array to receive the data.
int	nOS	Number of points to offset in buffer before starting read.
int	nWords	Number of 32-bit words to read (Samples).

Returns:

Type	Value	Description
int	0	Not successful.
int	1	Successful.

Reads 1000 points from a buffer (parameter tag labeled "datain") and stores it in a single array file (data).

Reads 1000 points from parameter tag labeled 'datain' to floating point array called data.

Python

data = RP.ReadTag('datain', 0, 1000)

ReadTagV

Reads variables stored in the processor device's memory into a PC buffer in variant format. ReadTagV should be used with MATLAB. Other programming languages should use ReadTag. See ReadTagVEX for alternative storage methods.

ReadTagV can be used with any component that has a data buffer, such as: RamBuffer, LongDynDel, FIR and so forth.

array ReadTagV(string Name, int nOS, int nWords);

Arguments:

Type	Argument	Description
string	Name	Name of parameter tag.
int	nOS	Number of points to offset in buffer before starting read.
int	nWords	Number of 32-bit words to read (Samples).

Returns:

Type	Value	Description
array	-1, or empty	Not successful.
array	Array	Successful.

Reads 1000 points from a buffer (parameter tag 'datain') and stores it in an array file (Data_A) as variant values.

MATLAB

Data_A = RP.ReadTagV('datain',0,1000);

See also: Continuous Acquire in the ActiveX examples.

ReadTagVEX

Reads data that has been written to a parameter tag and stored on the processor device. Data can be converted to one of five data formats (double, float, 32-, 16-, 8-bit Integer) and stored as either an array or a matrix. The user must specify the storage format of the data to be read (F32, 32-, 16-, or 8-bit Integer) and the number of channels.

When used to read compressed or shuffled data ReadTagVEX handles data manipulation and storage. Shuffled data is separated into channels and stored in a matrix. The nWords argument must be set to the number of samples in the serial buffer and is used along with nchannels to unshuffle or expand the data. For compressed data nWords must be set to the number of points after compression. e.g. If the data is compressed two-folded then only 500 samples of a 1000 point signal are contained in the serial buffer and nWords should be set to 500 (for a compression of 4 the number of points in the buffer would be 250).

ReadTagVEX is used with components that have a data Buffer, including: RamBuffer, Serial Buffer, Average Buffer, LongDelay, LongDynDelay, ShortDelay, ShortDynDelay, Biquad, IIR, FIR, HrtfFir.

Note: ReadTagVEX and WriteTagVEX are the only read/write commands that will work in languages other than MATLAB and Python

array ReadTagVEX(string Name, int nOS, int nWords, string stype, string dtype, int nchannels);

Arguments:

Type	Argument	Description
string	Name	Name of parameter tag.
int	nOS	Number of points to offset in buffer before starting read.
int	nWords	Number of 32-bit words to read (Samples).
string	Srctype	Format type of data being read. Below is a list of the storage types.

Floating Point (32-bit)	Word (32-bit)	Integer (16-bit)	Byte (8-bit)
F32	I32	I16	I8

Type	Argument	Description
string	Dsttype	Format for storing data. MATLAB handles data as doubles. All other languages use a variety of formats.

Double(64-bit float)	Float (32-bit)	Word (32-bit)	Integer(16-bit)	Byte(8-bit)
F64	F32	I32	I16	I8

Type	Argument	Description
int	nchannels	Number of data channels (1-4). For compressed and standard it is 1. For Shuffled data it is 2 or 4.

Returns:

Type	Value	Description
array	-1, or empty	Not successful.
array	Array	Successful.

MATLAB

Reads 1000 points from a processor device buffer (either compressed or Standard format) and stores it in an array of 1000 points in double format.

Data_A=RP.ReadTagVEX('datain',0,1000,'I16','F64',1);

Reads 1000 points from a processor device buffer that contains a shuffled data set (2-channels) and stores it in a matrix (2,500) in double format.

Data_A=RP.ReadTagVEX('datain',0,500,'I16','F64',2);

Reads 1000 points from a processor device buffer that contains a shuffled data set (2-channels) and stores it in a matrix (2,500) in 16-bit integer format.

Data_A=RP.ReadTagVEX("datain",0,500,"I16","I16",2)

See also: Two Channel Continuous Acquire in the ActiveX examples.

SetTagVal

Sets the value of the specified parameter tag.

int SetTagVal(string Name, float Val)

Arguments:

Type	Argument	Description
string	Name	Name of a parameter tag.
float	Val	Parameter tag value.

Returns:

Type	Value	Description
int	0	Not successful.
int	1	Successful.

Sets the parameter Tag value to that of the variable "rms".

MATLABPython

rms=5.0
e1=RP.SetTagVal('RMS', rms); % Set RMS Level

rms = 5.0
e1 = RP.SetTagVal('RMS', rms)  # Set RMS Level

See also: Band-limited Noise in the ActiveX examples.

WriteTag

Writes data from the PC to a memory buffer pointed to by a parameter tag. WriteTagV should be used with MATLAB. Other programming languages should use WriteTag. See WriteTagVEX for alternative methods of writing data.

WriteTag is used with the following components that have a data Buffer: RamBuffer, Serial Buffer, Average Buffer, LongDelay, LongDynDelay, ShortDelay, ShortDynDelay, Biquad, IIR,FIR, HrtfFir.

int WriteTag(string Name, float[] pBuf, int nOS, int nWords);

Arguments:

Type	Argument	Description
string	Name	Name of parameter tag.
float[]	pBuf	Array holding the data to load to the processor device's memory.
int	nOS	Number of points to offset in the processor device's memory before starting write.
int	nWords	Number of 32-bit words to write.

Returns:

Type	Value	Description
int	0	Not successful.
int	1	Successful.

Writes 1000 points from an array named 'data' to a memory buffer on the processor device (parameter tag labeled 'datain').

Python

# data holds the values to load
RP.WriteTag('datain', data, 0, 1000)

WriteTagV

Writes variables from the PC to a memory buffer on the processor device. WriteTagV should be used with MATLAB. Other programming languages should use WriteTag. WriteTagV is designed to take data in a standard MATLAB row vector. Column vectors should be transposed.

WriteTagV is used with the following components that have a data Buffer: RamBuffer, Serial Buffer, Average Buffer, LongDelay, LongDynDelay, ShortDelay, ShortDynDelay, Biquad, IIR,FIR, HrtfFir.

Note: WriteTagV is to be used in Matlab only with data type double. Attempting to write vectors of any other type will fail and return a zero.

See WriteTagVEX for alternative methods of writing vectors of all other data types.

int WriteTagV(string Name, int nOS, Variant &buffer);

Arguments:

Type	Argument	Description
string	Name	Name of parameter tag.
int	nOS	Number of points to offset in buffer before starting write.
array	&buffer	Data array with the samples.

Returns:

Type	Value	Description
int	0	Not successful.
int	1	Successful.

MATLAB

Writes 10000 points from an array (data) to a memory buffer on a processor device (pointed to by the parameter tag (datain)).

e1=RP.WriteTagV('datain', 0, data(1000:11000));

Writes 1000 points from an array (data) to a memory buffer on a processor device (pointed to by the parameter tag (datain)).

e1=RP.WriteTagV('datain', 0, data(0:1000));

See also: Continuous Play in the ActiveX examples.

WriteTagVEX

WriteTagVEX writes data stored in array or matrix format to a memory buffer on the processor device. The data format for storage in the memory buffer can be one of the following: 32-bit Float, 32-,16-, and 8-bit Integer formats. In addition, data is not limited to a single array format. The organization of variables stored in a matrix is preserved.

WriteTagVEX is used with the following components that have a data Buffer: RamBuffer, Serial Buffer, Average Buffer, LongDelay, LongDynDelay, ShortDelay, ShortDynDelay, Biquad, IIR, FIR, and HrtfFir.

Note: ReadTagVEX and WriteTagVEX are the only read/write commands that will work in languages other than MATLAB and Python

int WriteTagVEX(string Name, int nOS, string dtype, Variant &buffer);

Arguments:

Type	Argument	Description
string	Name	Name of parameter tag.
int	nOS	Number of points to offset in buffer before starting write.
string	dtype	One of four data types that the data is stored in.

Floating Point(32-bit)	Word(32-bit)	Integer(16-bit)	Byte(8-bit)
F32	I32	I16	I8

Type	Argument	Description
array	&buffer	Data array/matrix with the samples.

Returns:

Type	Value	Description
int	0	Not successful.
int	1	Successful.

MATLAB

Writes 10000 points from an array to a memory buffer on a processor device in floating point format.

e1=RP.WriteTagVEX('datain', 0, 'F32', data(1000:11000));

Writes 2000 points from a matrix (data) to a memory buffer on the processor device (pointed to by the parameter tag (datain) in integer format (16-bit).

e1=RP.WriteTagVEX('datain', 0, 'I16', data(1:2,1:1000));

See also: Two Channel Continuous Play in the ActiveX examples.

ZeroTag

Sets a parameter tag value to zero. When the parameter tag points to a memory buffer, all values in the buffer are set to zero.

int ZeroTag(string Name);

Arguments:

Type	Argument	Description
string	Name	Name of parameter tag.

Returns:

Type	Value	Description
int	0	Not successful.
int	1	Successful.

Sets membuf values to zero.

MATLAB

error1=RP.ZeroTag('membuf')