# ctaGetParmInfo

Retrieves a parameter field definition.

#### Prototype

DWORD ctaGetParmInfo ( unsigned parmid, char *parmname, unsigned index, CTA_PARM_INFO *buffer)

Argument | Description
parmid | Parameter structure ID.
parmname | Pointer to the parameter name (use NULL if the parmid specifies a valid parameter ID).
index | Relative field within the parameter structure.
buffer | Pointer to a buffer to receive a copy of CTA_PARM_INFO for the specified parameters. The CTA_PARM_INFO structure is: typedef struct { char structname[40]; char fieldname[40]; DWORD offset; DWORD size; DWORD format; DWORD units; } CTA_PARM_INFO; See the Details section for a description of these fields.

#### Return values

Return value | Description
SUCCESS |
CTAERR_BAD_ARGUMENT | buffer is NULL, or parmname is NULL and parmid is zero (0).
CTAERR_NOT_FOUND | parmname not found, parmid is invalid, or index is out of range.
CTAERR_NOT_INITIALIZED | Natural Access is not initialized. Call ctaInitialize first.
CTAERR_SVR_COMM | Server communication error.

#### Details

ctaGetParmInfo retrieves a field definition conveyed as a CTA_PARM_INFO structure. The parameter structure can be specified either by parmname or parmid.

If parmname is non-NULL, Natural Access searches for the parameter structure therein. The parmname format is svcname[.x].structname[.fieldname]. The service name and parameter structure name must be supplied, but the extension specifier and field name are optional. If the parameter or parameter structure are extensions to the standard service parameters, the literal text .x must be included in parmname.

If the field name is not supplied in parmname, Natural Access uses index as the field selector. The first field within the structure is indexed as zero (0), the second as one (1), and so on.

If parmname is NULL, parmid is used to retrieve the parameter structure and index is used as the field selector. The parameter IDs are defined in the service header file (for example, vcedef.h).

The IDs are usually of the following form: SERVICENAME[_X]_STRUCTNAME_PARMID.

The service name is the same name referenced in ctaInitialize and ctaOpenServices. If the structure references non-standard service extension parameters, the _X is used to distinguish these non-standard structures. An example of a standard structure parmid is VCE_PLAY_PARMID.

The returned CTA_PARM_INFO structure contains the following fields:

Field | Description
--- | ---
structname | The parameter's structure name. Use when using parmid.
fieldname | The parameter's field name.
offset | The value's offset in the parameter structure.
size | The parameter's value size (bytes).
format | The parameter's value format. Refer to the format table.
units | The parameter's value units. Refer to the unit table.

The following formats are supported:

Format | Description
--- | ---
CTA_FMT_WORD | Field is a 16-bit unsigned quantity.
CTA_FMT_DWORD | Field is a 32-bit unsigned quantity.
CTA_FMT_INT16 | Field is a 16-bit signed quantity.
CTA_FMT_INT32 | Field is a 32-bit signed quantity.
CTA_FMT_STRING | Field is a NULL-terminated string.
CTA_FMT_UNKNOWN | Field contains an unknown format.

The following units are supported:

Format | Description
--- | ---
CTA_UNITS_INTERNAL | No engineering units available.
CTA_UNITS_INTEGER | Field is a count or an index.
CTA_UNITS_COUNT | Field is a number of something.
CTA_UNITS_MASK | Field is a bit mask.
CTA_UNITS_HZ | Field is a measurement of frequency, in Hz.
CTA_UNITS_MS | Field is measured in milliseconds.
CTA_UNITS_DB | Field is a relative signal level, measured in dB.
CTA_UNITS_DBM | Field is an absolute signal level.
CTA_UNITS_IDU | Field is in internal DSP units (NMS internal representation for amplitude).
CTA_UNITS_STRING | Field contains a string.
CTA_UNITS_PERCENT | Field contains a percentage (where 100 is 100 percent).

Refer to Managing parameters for more information.

#### See also

ctaGetEventSources, ctaGetParmInfoEx, ctaGetParms, ctaSetEventSources

#### Example

void myShowParmInfo( char *parmname )
{
CTA_PARM_INFO info;
BYTE temp[100]; /* temp storage for parm value */
union
{
WORD w;
DWORD W;
INT16 i;
INT32 I;
char s[80];
} *pdata =( void* ) temp;
char *punits;
if( ctaGetParmInfo( 0, parmname, 0, &info ) != SUCCESS
|| ctaGetParmByName(NULL_CTAHD, parmname, &temp, sizeof( temp) )
!= SUCCESS )
{
/* display error */
return;
}
switch( info.units )
{
case CTA_UNITS_INTERNAL: punits = "Internal"; break;
case CTA_UNITS_INTEGER : punits = "Integer"; break;
case CTA_UNITS_COUNT : punits = "Count"; break;
case CTA_UNITS_MASK : punits = "Mask"; break;
case CTA_UNITS_HZ : punits = "Hz"; break;
case CTA_UNITS_MS : punits = "ms"; break;
case CTA_UNITS_DB : punits = "dB"; break;
case CTA_UNITS_DBM : punits = "dBm"; break;
case CTA_UNITS_IDU : punits = "Internal DSP"; break;
case CTA_UNITS_STRING : punits = "String"; break;
case CTA_UNITS_PERCENT : punits = "Percent"; break;
default : punits = "Undefined"; break;
}
switch( info.format )
{
case CTA_FMT_WORD:
printf( "%s.%-20s = %5u\t\t# (0x%04x) WORD (%s)\n",
info.structname, info.fieldname, pdata->w, pdata->w, punits );
break;
case CTA_FMT_DWORD:
printf( "%s.%-20s = %5u\t\t# (0x%04x) DWORD (%s)\n",
info.structname, info.fieldname, pdata->W, pdata->W, punits );
break;
case CTA_FMT_INT16:
printf( "%s.%-20s = %5d\t\t# (0x%04x) INT16 (%s)\n",
info.structname, info.fieldname, pdata->i, pdata->i, punits );
break;
case CTA_FMT_INT32:
printf( "%s.%-20s = %5d\t\t# (0x%04x) INT32 (%s)\n",
info.structname, info.fieldname, pdata->I, pdata->I, punits );
break;
case CTA_FMT_STRING:
printf( "%s.%-20s = \"%s\"\t\t# STRING[%d]\n",
info.structname, info.fieldname, pdata->s, info.size );
break;
default:
printf( "Error! Unknown data type: '%c'\n", info.format );
break;
}
return;
}

#### Sample run

For the parameter vce.play.gain, the output is:

vce.play.gain 0 # (0x0000) INT32 (dB)