The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session.

Pass a string containing the name of the repeated capability on which to operate. For instance, if you are working with the table of channel names, pass in the string "Channel".

Pass the ID you want the new attribute to have. Every attribute must have a distinct ID. You must define a constant name for the attribute in the include file for the instrument driver or in your source code. The constant name must begin with PREFIX_ATTR_, where PREFIX is the specific instrument prefix.

The include file for your specific instrument driver must define constant names for all of the user-accessible attributes that apply to the driver. This includes attributes that the IVI engine defines, attributes that the instrument class defines, and attributes that are specific to the particular instrument. Each defined constant name begins with PREFIX_ATTR_, where PREFIX is the specific instrument prefix.

For each IVI engine attribute, use the same constant name that appears in ivi.h, except replace the IVI prefix with the specific instrument prefix. For example, ivi.h defines IVI_ATTR_CACHE, and the Fluke 45 include file, fl45.h, defines the following constant name:

#define FL45_ATTR_CACHE  IVI_ATTR_CACHE

For each instrument class attribute, use the same constant name that appears in the instrument class include file, except replace the class prefix with the specific instrument prefix. For example, the DMM class include file, ividmm.h, defines IVIDMM_ATTR_RANGE, and fl45.h defines the following constant name:

#define FL45_ATTR_RANGE  IVIDMM_ATTR_RANGE

For each specific instrument attribute that the end-user can access, define a constant name in the instrument driver include file, and assign a value that is an offset from IVI_SPECIFIC_PUBLIC_ATTR_BASE. For example, fl45.h defines the following constant name:

#define FL45_ATTR_HOLD_THRESHOLD  \  (IVI_SPECIFIC_PUBLIC_ATTR_BASE + 3L)

For each attribute that is private to an instrument driver, define a constant name in the driver source file, and assign a value that is an offset from IVI_SPECIFIC_PRIVATE_ATTR_BASE. For example, hp34401a.c defines the following constant name:

#define HP34401A_ATTR_TRIGGER_TYPE  \  (IVI_SPECIFIC_PRIVATE_ATTR_BASE + 1L)

The name of the attribute. Specify the name to be the same as the defined constant name for the attribute ID.

For example, if the defined constant for this attribute is PREFIX_ATTR_RANGE, then pass "PREFIX_ATTR_RANGE".

Specify the default initial value for the attribute.

The IVI engine uses the default value in the following cases:

• IVI_ATTR_SIMULATION is enabled, you query the attribute value before you set it, and the IVI_VAL_USE_CALLBACKS_FOR_SIMULATION attribute is not set.
• The attribute does not have a read callback, and you query the attribute before you set it.

Specify the flags you want to set for this attribute. To set multiple flags, bitwise OR them together. For example, if you want the attribute to be hidden and never cached, then pass IVI_VAL_NOT_USER_WRITABLE | IVI_VAL_NEVER_CACHE.

You can query and modify the flags for an attribute using Ivi_GetAttributeFlags and Ivi_SetAttributeFlags.

Valid Values:

IVI_VAL_HIDDEN is 0x0018, the combination of IVI_VAL_NOT_USER_READABLE and IVI_VAL_NOT_USER_WRITABLE. Use the IVI_VAL_HIDDEN macro for attributes you do not want the end-user to access.

IVI_VAL_NOT_SUPPORTED–Indicates that the class driver creates the attribute but the specific driver does not implement it.

IVI_VAL_NOT_READABLE—Indicates that neither end-users nor instrument drivers can query the value of the attribute. Only the IVI engine can query the value of the attribute.

IVI_VAL_NOT_WRITABLE—Indicates that neither end-users nor instrument drivers can modify the value of the attribute. Only the IVI engine can modify the value of the attribute.

IVI_VAL_NOT_USER_READABLE—Indicates that end-users cannot query the value of the attribute. Only the IVI engine and instrument drivers can query the value of the attribute.

IVI_VAL_NOT_USER_WRITABLE—Indicates that end-users cannot modify the value of the attribute. Only the IVI engine and instrument drivers can modify the value of the attribute.

IVI_VAL_NEVER_CACHE—Directs the IVI engine never to use the cache value of the attribute, regardless of the state of the IVI_ATTR_CACHE attribute. The IVI engine always calls the read and write callbacks for the attribute, if present.

IVI_VAL_ALWAYS_CACHE—Directs the IVI engine to use the cache value of the attribute, if it is valid, regardless of the state of the IVI_ATTR_CACHE attribute.

IVI_VAL_MULTI_CHANNEL—Indicates that the attribute has a separate value for each channel. You cannot modify this flag using Ivi_SetAttributeFlags.

IVI_VAL_COERCEABLE_ONLY_BY_INSTR—Indicates that the instrument coerces values in a way that the instrument driver cannot anticipate in software. Do not use this flag unless the instrument's coercion algorithm is undocumented or too complicated to encapsulate in a range table or a coerce callback. When you query the value of an attribute for which this flag is set, the IVI engine ignores the cache value unless it obtained the cache value from the instrument. Thus, after you call an Ivi_SetAttribute function, the IVI engine invokes the read callback the next time you call an Ivi_GetAttribute function. When you set this flag, the IVI engine makes two assumptions that allow it to retain most of the benefits of state-caching:

1. The instrument always coerces the same value in the same way.
2. If you send the instrument a value that you obtained from the instrument, the instrument does not coerce the value. Based on these two assumptions, the IVI engine does not invoke the write callback for the attribute when you call an Ivi_SetAttribute function with the same value that you previously sent to, or received from, the instrument. If one or both of these assumption are not valid, use the IVI_VAL_NEVER_CACHE flag instead.

IVI_VAL_WAIT_FOR_OPC_BEFORE_READS—Directs the IVI engine to call the operation complete callback for the session before calling the read callback for the attribute.

IVI_VAL_WAIT_FOR_OPC_AFTER_WRITES—Directs the IVI engine to call the operation complete callback for the session after calling the write callback for the attribute.

IVI_VAL_USE_CALLBACKS_FOR_SIMULATION—Directs the IVI engine to invoke the read and write callbacks for the attribute even when in simulation mode.

IVI_VAL_DONT_CHECK_STATUS—By default, when an end-user calls one of the PREFIX_GetAttribute or PREFIX_SetAttribute functions in an instrument driver and the IVI_ATTR_QUERY_INSTRUMENT_STATUS attribute is enabled, the IVI engine calls the check status callback for the session after calling the read or write callback for the attribute. This flag directs the IVI engine never to call the check status callback for the attribute.

Specify the read callback function you want the IVI engine to invoke when you request the current value of the attribute.

You must define the read callback function in the source code for the specific instrument driver. The function must have the following prototype:

ViStatus _VI_FUNC Callback (ViSession vi, ViSession io, ViConstString repCapName, ViAttr attributeId, ViAddr *value);

Upon entry to the callback, *value contains the cache value. Upon exit from the callback, *value must contain the actual current value.

Note  If you want to use the Edit IVI Specific Driver Attributes dialog box to develop your instrument driver source code, retain the parameter names as shown in the prototype for the callback.

If you do not want to use a read callback function, pass VI_NULL.

You can change the callback at a later time by calling Ivi_SetAttrReadCallbackViAddr.

Specify the write callback function you want the IVI engine to invoke when you set the attribute to a new value.

You must define the write callback function in the source code for the specific instrument driver. The function must have the following prototype:

ViStatus _VI_FUNC Callback (ViSession vi, ViSession io, ViConstString repCapName, ViAttr attributeId, ViAddr value);

Note  If you want to use the Edit IVI Specific Driver Attributes dialog box to develop your instrument driver source code, retain the parameter names as shown in the prototype for the callback.

If you do not want to use a write callback function, pass VI_NULL.

You can change the callback at a later time by calling Ivi_SetAttrWriteCallbackViAddr.