Ivi_RangeTableNew
Usage
ViStatus Ivi_RangeTableNew(ViSession vi, ViInt32 numberOfEntries, ViInt32 typeOfTable, ViBoolean hasMinimum, ViBoolean hasMaximum, IviRangeTablePtr* rangeTable);
Purpose
This function dynamically allocates a range table. Range tables you create with this function are called "dynamic range tables". Range tables you define statically in your source code are called "static range tables".
If the values in the range table for a particular attribute can change depending on the settings of other attributes, you must create it as a dynamic range table. You must also install a range table callback using Ivi_SetAttrRangeTableCallback. In the range table callback, you modify the contents of the range table and then return its address.
To allow for multithreading and multiple sessions to the same instrument type, you must create a separate dynamic range table for each IVI session. It is convenient to pass the address of the dynamic range table to Ivi_AddAttributeViInt32 or Ivi_AddAttributeViReal64 when you create the attribute. Your range table callback can then use the Ivi_GetStoredRangeTablePtr function to obtain the address of the dynamic range table for the session.
This function allocates the IviRangeTable structure and an array of IviRangeTableEntry structures. It allocates space in the array for the number of entries you specify, which must include the termination entry. It sets the last entry as the termination entry. Use the Ivi_SetRangeTableEntry function to set the values within the entries.
If the number of entries in the table varies, specify the maximum number of entries that it can contain. Use the Ivi_SetRangeTableEnd function to change the location of the termination entry.
The IVI engine keeps track of the memory you allocate with this function in each session. It automatically frees the memory when you call Ivi_Dispose on the session.
If you want to deallocate the table before the session ends, call the Ivi_RangeTableFree function.
Parameters
| Name | Type | Description | ||
|---|---|---|---|---|
| vi | ViSession |
The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session. |
||
| numberOfEntries | ViInt32 |
Specify the number of entries you want in the range table, including the termination entry. For example, if you want to have 6 entries in the range table, excluding the termination entry, pass 7 for this parameter. The function automatically sets the last entry as the termination entry. To set an earlier entry as the termination entry, call Ivi_SetRangeTableEnd. |
||
| typeOfTable | ViInt32 |
Specify the type of range table you want to create. The type indicates how the IVI engine interprets the discreteOrMinValue, maxValue, and coercedValue fields in each entry. Valid Values: (0) IVI_VAL_DISCRETE (1) IVI_VAL_RANGED (2) IVI_VAL_COERCED (1) Discrete—Each table entry defines a discrete value. The discreteOrMinValue field contains the discrete value. The maxValue and coercedValue fields are not used. (2) Ranged—Each table entry defines a range with a minimum and a maximum value. The discreteOrMinValue field holds the minimum value, and the maxValue field holds the maximum value. The coercedValue field is not used. If the attribute has only one continuous valid range and you do not assign different command strings or command values to subsets of the range, create the range table with only one entry other than the terminating entry. (3) Coerced—Each table entry defines a discrete value that represents a range of values. This is useful when an instrument supports a set of ranges, each of which you must specify to the instrument with one discrete value. The discreteOrMinValue holds the minimum value of the range, maxValue holds the maximum value, and coercedValue holds the discrete value that represents the range. |
||
| hasMinimum | ViBoolean |
Indicates whether the table contains a meaningful minimum value. Pass VI_TRUE (1) if the range table has a meaningful minimum valid value. Otherwise, pass VI_FALSE (0).
|
||
| hasMaximum | ViBoolean |
Indicates whether the table contains a meaningful maximum value. Pass VI_TRUE (1) if the range table has a meaningful maximum valid value. Otherwise, pass VI_FALSE (0).
|
||
| rangeTable | IviRangeTablePtr* |
Returns a pointer to the range table the function dynamically allocates. Use Ivi_SetRangeTableEntry to configure each entry after calling this function. |
Return Value
Contains the status code that the function call returns. IVI engine functions can return error and warning values from several sets of status codes. Some status codes are unique to the IVI engine. Other status codes are the same codes that VISA Library functions return. Still others are error or warning values that functions in specific instrument drivers return. Each set of status codes has its own numeric range.
Regardless of the source of the status code, 0 always indicates success, a positive value indicates a warning, and a negative value indicates an error.