Minimizing Code Growth Within an IVI Instrument Driver

Sharing Attribute Range Tables

Range tables are powerful software tools that define the values to which an attribute may be set. This ability allows you to verify an attribute value before you perform any instrument I/O, and it can greatly minimize the occurrence of I/O errors. As stated earlier, code growth can occur when different range tables are created for attributes with similar ranges.

Consider the following example. The attributes amDepth and dutyCycle are both expressed as percentages and can range from 0.0 to 100.0. At first, you might quickly implement two separate range tables for these attributes as follows:

static IviRangeTableEntry amDepth_RangeTableEntries[] =
{
{0.0, 100.0, 0, "", 0},
{IVI_RANGE_TABLE_LAST_ENTRY}
};
static IviRangeTable amDepth_RangeTable =
{
IVI_VAL_RANGED,
VI_TRUE,
VI_TRUE,
VI_NULL,
amDepth_RangeTableEntries,
};

static IviRangeTableEntry dutyCycle_RangeTableEntries[] =
{
{0.0, 100.0, 0, "", 0},
{IVI_RANGE_TABLE_LAST_ENTRY}
};
static IviRangeTable dutyCycle_RangeTable =
{
IVI_VAL_RANGED,
VI_TRUE,
VI_TRUE,
VI_NULL,
dutyCycle_RangeTableEntries,
};

This approach is perfectly valid. It would compile and run without any problems. However, this code is repetitious. The two attributes have identical ranges and are of the same type: VIReal64. In fact, the two range tables are identical in every respect except for their names.

When you have only two attributes with identical ranges, the cost of an extra range table is not particularly noticeable. However, if you have 10 or even more attributes that are given as percentages, the repetition of code can become quite costly. A better approach is to create a percentage range table, as shown below. This range table is more generalized and can be used by any attribute with the same range:

static IviRangeTableEntry percentageRangeTableEntries[] =
{
{0.0, 100.0, 0, "", 0},
{IVI_RANGE_TABLE_LAST_ENTRY}
};
static IviRangeTable percentageRangeTable =
{
IVI_VAL_RANGED,
VI_TRUE,
VI_TRUE,
VI_NULL,
percentageRangeTableEntries,
};

After creating one range table which can be shared by multiple attributes, you also need to configure each attribute to use it. One way to configure the attributes is by changing the range table parameter in the Ivi_AddAttribute<type> function of each attribute. You pass the address of the range table to the function:

Ivi_AddAttributeViReal64 (instrument_handle, ATTRIBUTE_1,
"ATTRIBUTE_1", default_value,
attibute1_flags, attribute1_ReadCallback,
attribute1_WriteCallback,
&percentageRangeTable);

Another way to configure the attributes is by using the Attribute Editor in LabWindows/CVI. Double-click the desired attribute and then change the range table parameter as shown below.

Sharing Utility Routines

The following two functions are taken from the hp34401a driver. These two functions, init and InitWithOptions, can also be found in every other IVI-compliant instrument driver:

ViStatus _VI_FUNC hp34401a_init (ViRsrc resourceName, ViBoolean IDQuery,
ViBoolean resetDevice, ViSession *newVi)
{
ViStatus error = VI_SUCCESS;

if (newVi == VI_NULL)
{
Ivi_SetErrorInfo (VI_NULL, VI_FALSE, IVI_ERROR_INVALID_PARAMETER,
VI_ERROR_PARAMETER4, "Null address for Instrument
Handle");
checkErr( IVI_ERROR_INVALID_PARAMETER);
}

checkErr( hp34401a_InitWithOptions (resourceName, IDQuery, resetDevice,
"", newVi));
Error:
return error;
}

ViStatus _VI_FUNC hp34401a_InitWithOptions (ViRsrc resourceName,
ViBoolean IDQuery,
ViBoolean resetDevice,
ViString optionString,
ViSession *newVi)
{
ViStatus error = VI_SUCCESS;
ViSession vi = VI_NULL;
ViChar newResourceName[IVI_MAX_MESSAGE_BUF_SIZE];
ViChar newOptionString[IVI_MAX_MESSAGE_BUF_SIZE];
ViBoolean isLogicalName;

if (newVi == VI_NULL)
{
Ivi_SetErrorInfo (VI_NULL, VI_FALSE, IVI_ERROR_INVALID_PARAMETER,
VI_ERROR_PARAMETER5, "Null address for Instrument
Handle");
checkErr( IVI_ERROR_INVALID_PARAMETER);
}

*newVi = VI_NULL;
checkErr( Ivi_GetInfoFromResourceName (resourceName, optionString,
newResourceName, newOptionString,
&isLogicalName));

checkErr( Ivi_SpecificDriverNew ("hp34401a", newOptionString, &vi));
checkErr( hp34401a_IviInit (newResourceName, IDQuery, resetDevice, vi));

if (isLogicalName)
checkErr( Ivi_ApplyDefaultSetup (vi));

*newVi = vi;

Error:
if (error < VI_SUCCESS)
Ivi_Dispose (vi);
return error;
}

Notice that the init function calls the InitWithOptions function with an empty option string. Furthermore, the only operation performed by init before it calls InitWithOptions is parameter checking, which is also done by InitWithOptions. The parameter checking is redundant. The check must be performed in the InitWithOptions function because, like init, this function is exported to the user. The check must also be done in the init function because, although the parameter newVi being checked is the same, the parameter numbers are different between the functions. Thus, different VISA error codes must be passed to the Ivi_SetErrorInfo function.

You can remove the redundant checking by restructuring the code so that the init function does not call the InitWithOptions function at all. The two functions should behave as separate entities, each doing its own specific error checking and then performing similar initialization routines.

You can write a utility function called initialize that actually performs the initialization:

static ViStatus initialize (ViRsrc resourceName,
ViBoolean IDQuery,
ViBoolean resetDevice,
ViString optionString,
ViSession *newVi)
{
ViSession vi = VI_NULL;
ViChar newResourceName[IVI_MAX_MESSAGE_BUF_SIZE];
ViChar newOptionString[IVI_MAX_MESSAGE_BUF_SIZE];
ViBoolean isLogicalName;

*newVi = VI_NULL;
checkErr( Ivi_GetInfoFromResourceName (resourceName, optionString,
newResourceName, newOptionString,
&isLogicalName));

checkErr( Ivi_SpecificDriverNew ("hp34401a", newOptionString, &vi));

checkErr( hp34401a_IviInit (newResourceName, IDQuery, resetDevice, vi));
if (isLogicalName)
checkErr( Ivi_ApplyDefaultSetup (vi));

*newVi = vi;

Error:
if (error < VI_SUCCESS)
Ivi_Dispose (vi);
return error;
}

Now, the init and InitWithOptions functions should call initialize:

ViStatus _VI_FUNC hp34401a_init (ViRsrc resourceName, ViBoolean IDQuery,
ViBoolean resetDevice, ViSession *newVi)
{
ViStatus error = VI_SUCCESS;

if (newVi == VI_NULL)
{
Ivi_SetErrorInfo (VI_NULL, VI_FALSE, IVI_ERROR_INVALID_PARAMETER,
VI_ERROR_PARAMETER4, "Null address for Instrument
Handle");
checkErr( IVI_ERROR_INVALID_PARAMETER);
}

checkErr( initialize (resourceName, IDQuery, resetDevice, newVi));

Error:
return error;
}


ViStatus _VI_FUNC hp34401a_InitWithOptions (ViRsrc resourceName,
ViBoolean IDQuery,
ViBoolean resetDevice,
ViString optionString,
ViSession *newVi)
{
ViStatus error = VI_SUCCESS;

if (newVi == VI_NULL)
{
Ivi_SetErrorInfo (VI_NULL, VI_FALSE, IVI_ERROR_INVALID_PARAMETER,
VI_ERROR_PARAMETER5, "Null address for Instrument"
"Handle");
checkErr( IVI_ERROR_INVALID_PARAMETER);
}

checkErr( initialize (resourceName, IDQuery, resetDevice, newVi));

Error:
return error;
}

Conclusion

2 ratings | 4.00 out of 5

Print

Reader Comments | Submit a comment »