Table of Contents. Pickering Instruments IVI Driver Help... 1 Contents... 1 Getting Started... 3 Introduction... 3 Essential Functions... 4 LXI...

Transcription

1 Table of Contents Pickering Instruments IVI Driver Help... 1 Contents... 1 Getting Started... 3 Introduction... 3 Essential Functions... 4 LXI... 5 LXISpecific... 5 PXI and PCI... 5 PXISpecific... 5 GPIB... 5 GPIBSpecific... 5 VXI... 5 VXISpecific... 5 RS RS232Specific... 5 Channel Names... 6 Contact Pickering... 7 Attributes... 8 PI40IV_ATTR_BANDWIDTH... 8 PI40IV_ATTR_CACHE PI40IV_ATTR_CHANNEL_COUNT... PI40IV_ATTR_CHARACTERISTIC_IMPEDANCE PI40IV_ATTR_DRIVER_SETUP PI40IV_ATTR_ERROR_ELABORATION PI40IV_ATTR_GROUP_CAPABILITIES PI40IV_ATTR_INSTRUMENT_FIRMWARE_REVISION PI40IV_ATTR_INSTRUMENT_MANUFACTURER PI40IV_ATTR_INSTRUMENT_MODEL PI40IV_ATTR_INTERCHANGE_CHECK PI40IV_ATTR_IO_RESOURCE_DESCRIPTOR PI40IV_ATTR_IO_SESSION PI40IV_ATTR_IO_SESSION_TYPE PI40IV_ATTR_IS_CONFIGURATION_CHANNEL PI40IV_ATTR_IS_DEBOUNCED PI40IV_ATTR_IS_SOURCE_CHANNEL PI40IV_ATTR_LOGICAL_NAME PI40IV_ATTR_MAX_AC_VOLTAGE PI40IV_ATTR_MAX_CARRY_AC_CURRENT PI40IV_ATTR_MAX_CARRY_AC_POWER PI40IV_ATTR_MAX_CARRY_DC_CURRENT PI40IV_ATTR_MAX_CARRY_DC_POWER PI40IV_ATTR_MAX_DC_VOLTAGE PI40IV_ATTR_MAX_SWITCHING_AC_CURRENT PI40IV_ATTR_MAX_SWITCHING_AC_POWER PI40IV_ATTR_MAX_SWITCHING_DC_CURRENT PI40IV_ATTR_MAX_SWITCHING_DC_POWER PI40IV_ATTR_NUM_OF_COLUMNS PI40IV_ATTR_NUM_OF_ROWS PI40IV_ATTR_PRIMARY_ERROR PI40IV_ATTR_QUERY_INSTRUMENT_STATUS... 39

2 40 PI40IV_ATTR_RANGE_CHECK PI40IV_ATTR_RECORD_COERCIONS PI40IV_ATTR_SECONDARY_ERROR PI40IV_ATTR_SETTLING_TIME PI40IV_ATTR_SIMULATE PI40IV_ATTR_SPECIFIC_DRIVER_CLASS_SPEC_MAJOR_VERSION PI40IV_ATTR_SPECIFIC_DRIVER_CLASS_SPEC_MINOR_VERSION PI40IV_ATTR_SPECIFIC_DRIVER_DESCRIPTION PI40IV_ATTR_SPECIFIC_DRIVER_MAJOR_VERSION PI40IV_ATTR_SPECIFIC_DRIVER_MINOR_VERSION PI40IV_ATTR_SPECIFIC_DRIVER_PREFIX PI40IV_ATTR_SPECIFIC_DRIVER_REVISION PI40IV_ATTR_SPECIFIC_DRIVER_VENDOR PI40IV_ATTR_SUPPORTED_INSTRUMENT_MODELS PI40IV_ATTR_WIRE_MODE PI40IV_ATTR_VXI_MANF_ID PI40IV_ATTR_VXI_MODEL_CODE Functions Route Paths pi40iv_getpath pi40iv_setpath pi40iv_connect pi40iv_disconnect pi40iv_disconnectall pi40iv_isdebounced pi40iv_canconnect pi40iv_waitfordebounce Configuration Get Attribute pi40iv_getattributeviboolean pi40iv_getattributeviint pi40iv_getattributevireal pi40iv_getattributevisession pi40iv_getattributevistring Check Attribute pi40iv_checkattributeviboolean pi40iv_checkattributeviint pi40iv_checkattributevireal pi40iv_checkattributevisession pi40iv_checkattributevistring Set Attribute pi40iv_setattributeviboolean pi40iv_setattributeviint pi40iv_setattributevireal pi40iv_setattributevisession pi40iv_setattributevistring Utility Error Info pi40iv_geterror pi40iv_clearerror Coercion Info pi40iv_getnextcoercionrecord Instrument I/O...

3 pi40iv_readinstrdata pi40iv_writeinstrdata Lock/Unlock Session pi40iv_locksession pi40iv_unlocksession Interchangeability Info pi40iv_getnextinterchangewarning pi40iv_clearinterchangewarning pi40iv_resetinterchangecheck pi40iv_error_message pi40iv_error_query pi40iv_invalidateallattributes pi40iv_revision_query pi40iv_reset pi40iv_resetwithdefaults pi40iv_self_test pi40iv_disable pi40iv_getchannelname pi40iv_close pi40iv_init pi40iv_initwithoptions Pickering Custom Specific Functions Pickering Custom Specific Driver Functions Data Formats pi40iv_getnumberinputsubs pi40iv_getinputsizebits pi40iv_getinputsizedwords pi40iv_getinputbit pi40iv_getinputsub pi40iv_getnumberoutputsubs pi40iv_getoutputsizebits pi40iv_getoutputsizedwords pi40iv_setoutputbit pi40iv_setoutputsub pi40iv_getoutputbit pi40iv_getoutputsub pi40iv_subinfo Obsolete and non-implemented functions and attributes PI40IV_ATTR_QUERY_INSTR_STATUS PI40IV_ATTR_NUM_CHANNELS PI40IV_ATTR_RESOURCE_DESCRIPTOR pi40iv_clearerrorinfo pi40iv_geterrorinfo PI40IV_ATTR_IS_SCANNING PI40IV_ATTR_SCAN_ADVANCED_OUTPUT PI40IV_ATTR_SCAN_DELAY PI40IV_ATTR_SCAN_LIST PI40IV_ATTR_SCAN_MODE Additional Information Configurable Products More driver info Multiplex Specific Requirements Driver Setup Examples Glossary

4 171 Attribute List Supported modules Error Codes...

5 Contents Contents Introduction Assumptions Contents Attribute List Error Codes Channel names Supported modules More driver info Configurable Products Contact Pickering Function Tree Layout: Class/Panel Name: Function Name: Initialize (not supported) pi40iv_init (not supported) Initialize With Options pi40iv_initwithoptions Configuration Set Attribute Set Attribute ViInt32 Set Attribute ViReal64 pi40iv_setattributeviint32 pi40iv_setattributevireal64 Set Attribute ViString pi40iv_setattributevistring Set Attribute ViBoolean pi40iv_setattributeviboolean Set Attribute ViSession pi40iv_setattributevisession Get Attribute Get Attribute ViInt32 pi40iv_getattributeviint32 Get Attribute ViReal64 pi40iv_getattributevireal64 Get Attribute ViString pi40iv_getattributevistring Get Attribute ViBoolean pi40iv_getattributeviboolean Get Attribute ViSession pi40iv_getattributevisession Check Attribute Check Attribute ViInt32 pi40iv_checkattributeviint32 Check Attribute ViReal64 pi40iv_checkattributevireal64 Check Attribute ViString pi40iv_checkattributevistring Check Attribute ViBoolean pi40iv_checkattributeviboolean Check Attribute ViSession pi40iv_checkattributevisession Route Connect Channels Disconnect Channels Disconnect All Channels Switch Is Debounced? Wait For Debounce Can Connect Channels? Paths Set Path Get Path Utility Reset ResetWithDefaults Disable Self-Test Revision Query Error-Query Error Message InvalidateAllAttributes GetChannelName Error Info Get Error Clear Error pi40iv_connect pi40iv_disconnect pi40iv_disconnectall pi40iv_isdebounced pi40iv_waitfordebounce pi40iv_canconnect pi40iv_setpath pi40iv_getpath pi40iv_reset pi40iv_resetwithdefaults pi40iv_disable pi40iv_self_test pi40iv_revision_query pi40iv_error_query pi40iv_error_message ipi40iv_invalidateallattributes pi40iv_getchannelname pi40iv_geterror pi40iv_clearerror 1 / 208

6 Coercion Info Get Next Coercion Record pi40iv_getnextcoercionrecord Interchangeability Info Get Next Interchange Warning pi40iv_getnextinterchangewarning Clear Interchange Warningpi40iv_ClearInterchangeWarning Reset Interchange Check pi40iv_resetinterchangecheck Locking Lock Session pi40iv_locksession Unlock Session pi40iv_unlocksession Instrument I/O Write Instrument Data Read Instrument Data pi40iv_writeinstrdata pi40iv_readinstrdata Close Pickering Custom Specific Functions GetNumberInputSubs pi40iv_getnumberinputsubs GetInputSizeBits pi40iv_getinputsizebits GetInputSizeDwords GetInputBit pi40iv_getinputsizedwords pi40iv_getinputbit GetInputSub pi40iv_getinputsub GetNumberOutputSubs GetOutputSizeBits pi40iv_getnumberoutputsubs pi40iv_getoutputsizebits GetOutputSizeDwords pi40iv_getoutputsizedwords SetOutputBit pi40iv_setoutputbit SetOutputSub pi40iv_setoutputsub GetOutputBit GetOutputSub pi40iv_getoutputbit pi40iv_getoutputsub SubInfo pi40iv_subinfo Contents 2 / 208

7 Introduction Pickering Interfaces PXI Switching IVI Driver This Help information describes IVI programming support for Pickering Interfaces PXI switching cards. Pi40iv is an Interchangeable Virtual Instrument (IVI ) compliant driver that supports all System 40 (3U PXI), System 45 (6U PXI) and System 50 (PCI) switching cards. This driver has all the functions that IVI and VXIplug&play require. The target framework for this driver is WIN32, which provides 32 bit application support for Microsoft Windows versions 95/98/ME/NT/2000/XP. This driver uses the facilities of VPP Virtual Instrument Software Architecture (VISA ) functions for communicating with the instrument. Information on IVI and VISA can be found at the IVI Foundation open consortium website at The driver requires NI-VISA version 2.6 or greater to be installed on the host system for its operation (VISA version 2.2.0, implementation 2.6.0). The driver also needs the IVI libraries: IVI Engine and IVI class drivers. The pi40iv driver installation contains the core driver DLLs, support files, help files and sample programs. System 40, System 45 and System 50 cards offer a wide range of Relay Switching and Digital Input-Output functions in PXI, CompactPCI and PCI formats. For more information contact pickering. Note: This driver requires the VISA and IVI libraries. 3 / 208

8 Essential Functions Essential Functions This IVI driver provides a session based API and so all programs which use it will contain the following three steps: 1 Open a card and get a Session ID. Use the pi40iv_initwithoptions function. 2 Control or interrogate the card (throw switches, read card state etc) using the Session ID. a To control the card these functions will be of interest: b To interrogate the card these functions will be of interest: 3 Close the card (release it for use by other programs) using the session ID. Use the pi40iv_close Nearly all of the IVI functions return a status value of 0 (C Constant VI_SUCCESS) for successful completion, or non 0 for unsuccessful. Use the pi40iv_error_message function to convert this to a meaningful text message. 4 / 208

9 RS232Specific Assumptions To successfully use this module, the following conditions must be met: For LXI instrument drivers: the card is installed in an LXI chassis and you have an ethernet connection to your controller. the logical address supplied to the initialize function must match the logical address of the instrument. For PXI (and PCI) instrument drivers: the instrument is installed in the PXI mainframe (for PCI modules: installed in a PCI slot) and you are using one of the following controller options: Embedded controller - PC to PXI bridge system e.g. MXI3 Directly connected to a PCI slot. the logical address supplied to the initialize function must match the logical address of the instrument. For GPIB instrument drivers: the instrument is connected to the GPIB. the GPIB address supplied to the initialize function must match the GPIB address of the instrument. For VXI instrument drivers: the instrument is installed in the VXI mainframe and you are using one of the following controller options: Embedded controller - PC to VXI bridge system e.g. MXI, MXI2 GPIB-VXI the logical address supplied to the initialize function must match the logical address of the instrument. For RS-232 instrument drivers: the instrument is connected to the RS-232 interface. the COM port, baud rate, parity, and timeout supplied to the initialize function must match the settings of the instrument. 5 / 208

10 Channel Names Channel Names See below what channel names to use for your switch card depending on what type it is. Switch card Channel names: examples: Matrix card x1,x2,x3,y1,y2,y3 (3x3) Multiplexer card com,ch1,ch2,ch3,ch4 (4x1) General purpose com1,ch1,com2,ch2,com3,ch3 card (3 relays) Changeover relay card (3 relays) Dual, quad card examples: Dual matrix (3x3) com1,no1,nc1,com2,no2,nc2,com3,no3 (no = normally open, nc = normally closed) xa1,xa2,xa3,ya1,ya2,ya3,xb1,xb2,xb3,yb1,yb2,yb3 (A/B indicating which matrix) Quad mux (4x1) coma,cha1,cha2,cha3,cha4,comb,chb1,chb2,chb3, chb4,comc,chc1,chc2,chc3,chc4,comd,chd1,chd2,chd3,chd4 (A/B/C/D indicating which mux) 6 / 208

11 Contact Pickering Contact Pickering For further assistance, please contact: Pickering Interfaces Ltd. Stephenson Road Clacton-on-Sea Essex CO15 4NL UK Tel. +44 (0) Fax. +44 (0) Regional contact details are available from our website: (sales): (technical support): Other useful links PXI Systems Alliance (PXISA): PCI Industrial Computer Manufacturers Group (PICMG): PCI Special Interest Group (PCI-SIG): VXIPlug&Play Systems Alliance: 7 / 208

12 PI40IV_ATTR_BANDWIDTH PI40IV_ATTR_BANDWIDTH Data Type: ViReal64 Restrictions: Not settable. Description: This channel-based attribute returns the bandwidth for the channel. The units are hertz. 8 / 208

13 PI40IV_ATTR_CACHE PI40IV_ATTR_CACHE Data Type: Restrictions: Description: ViBoolean Specifies whether to cache the value of attributes. When caching is enabled, the instrument driver keeps track of the current instrument settings and avoids sending redundant commands to the instrument. Thus, you can significantly increase execution speed. The instrument driver can choose always to cache or never to cache particular attributes regardless of the setting of this attribute. The default value is VI_TRUE. Use the pi40iv_initwithoptions function to override this value. 9 / 208

14 PI40IV_ATTR_CHANNEL_COUNT PI40IV_ATTR_CHANNEL_COUNT Data Type: ViInt32 Restrictions: Not settable. Description: Indicates the number of channels that the specific instrument driver supports. For each attribute for which the IVI_VAL_MULTI_CHANNEL flag attribute is set, the IVI engine maintains a separate cache value for each channel. 10 / 208

15 PI40IV_ATTR_CHARACTERISTIC_IMPEDANCE PI40IV_ATTR_CHARACTERISTIC_IMPEDANCE Data Type: ViReal64 Restrictions: Not settable. Description: This channel-based attribute returns the characteristic impedance for the channel. The units are ohms. 11 / 208

16 PI40IV_ATTR_DRIVER_SETUP PI40IV_ATTR_DRIVER_SETUP Data Type: Restrictions: Description: ViString This attribute indicates the Driver Setup string that the user specified when initializing the driver. Some cases exist where the end-user must specify instrument driver options at initialization time. An example of this is specifying a particular instrument model from among a family of instruments that the driver supports. This is useful when using simulation. The end-user can specify driver-specific options through the DriverSetup keyword in the optionsstring parameter to the pi40iv_initwithoptions function, or through the IVI Configuration Utility. If the user does not specify a Driver Setup string, this attribute returns an empty string. Note: See Driver Setup Examples. 12 / 208

17 PI40IV_ATTR_ERROR_ELABORATION PI40IV_ATTR_ERROR_ELABORATION (*not needed) Data Type: Restrictions: Description: ViString An optional string that contains additional information concerning the primary error condition. * This function is only needed for the obsolete functions pi40iv_geterrorinfo and pi40iv_clearerrorinfo. 13 / 208

18 PI40IV_ATTR_GROUP_CAPABILITIES PI40IV_ATTR_GROUP_CAPABILITIES Data Type: ViString Restrictions: Not settable. Description: A string that contains a comma-separated list of class-extention groups that this driver implements. 14 / 208

19 PI40IV_ATTR_INSTRUMENT_FIRMWARE_REVISION PI40IV_ATTR_INSTRUMENT_FIRMWARE_REVISION Data Type: ViString Restrictions: Not settable. Description: A string that contains the firmware revision information for the instrument you are currently using. 15 / 208

20 PI40IV_ATTR_INSTRUMENT_MANUFACTURER PI40IV_ATTR_INSTRUMENT_MANUFACTURER Data Type: ViString Restrictions: Not settable. Description: A string that contains the name of the instrument manufacturer you are currently using. 16 / 208

21 PI40IV_ATTR_INSTRUMENT_MODEL PI40IV_ATTR_INSTRUMENT_MODEL Data Type: ViString Restrictions: Not settable. Description: A string that contains the model number or name of the instrument that you are currently using. 17 / 208

22 PI40IV_ATTR_INTERCHANGE_CHECK PI40IV_ATTR_INTERCHANGE_CHECK Data Type: ViBoolean Restrictions: Description: Specifies whether to perform interchangeability checking and retrieve interchangeability warnings when you call pi40iv_connect and pi40iv_setpath functions. The default value is VI_FALSE. Interchangeability warnings indicate that using your application with a different instrument might cause different behavior. You call pi40iv_getnextinterchangewarning to extract interchange warnings. Call the pi40iv_clearinterchangewarnings function to clear the list of interchangeability warnings without reading them. Interchangeability checking examines the attributes in a capability group only if you specify a value for at least one attribute within that group. Interchangeability warnings can occur when an attribute affects the behavior of the instrument and you have not set that attribute, or the attribute has been invalidated since you set it. 18 / 208

23 PI40IV_ATTR_IO_RESOURCE_DESCRIPTOR PI40IV_ATTR_IO_RESOURCE_DESCRIPTOR Data Type: ViString Restrictions: Not settable. Description: Indicates the resource descriptor the driver uses to identify the physical device. If you initialize the driver with a logical name, this attribute contains the resource descriptor that corresponds to the entry in the IVI Configuration utility. If you initialize the instrument driver with the resource descriptor, this attribute contains that value. 19 / 208

24 PI40IV_ATTR_IO_SESSION PI40IV_ATTR_IO_SESSION Data Type: ViSession Restrictions: Not settable. Description: Specifies the I/O session that the specific driver uses to communicate with the instrument. 20 / 208

25 PI40IV_ATTR_IO_SESSION_TYPE PI40IV_ATTR_IO_SESSION_TYPE Data Type: ViString Restrictions: Not settable. Description: Contains the type of the I/O session that this driver uses to communicate with the instrument. 21 / 208

26 PI40IV_ATTR_IS_CONFIGURATION_CHANNEL PI40IV_ATTR_IS_CONFIGURATION_CHANNEL Data Type: ViBoolean Restrictions: Description: This channel-based attribute specifies whether to reserve the channel for internal path creation. A channel that is available for internal path creation is called a configuration channel. The driver may use configuration channels to create paths between two channels you specify in the pi40iv_connect function. Configuration channels are not available for external connections. Set this attribute to VI_TRUE to mark the channel as a configuration channel. Set this attribute to VI_FALSE to mark the channel as available for external connections. After you identify a channel as a configuration channel, you cannot use that channel for external connections. The pi40iv_connect function returns the PI40IV_ERROR_IS_CONFIGURATION_CHANNEL error when you attempt to establish a connection between a configuration channel and any other channel. 22 / 208

27 PI40IV_ATTR_IS_DEBOUNCED PI40IV_ATTR_IS_DEBOUNCED Data Type: ViBoolean Restrictions: Not settable. Description: This attribute indicates whether the entire switch module has settled since the last switching command. A value of VI_TRUE indicates that all signals going through the switch module are valid. 23 / 208

28 PI40IV_ATTR_IS_SOURCE_CHANNEL PI40IV_ATTR_IS_SOURCE_CHANNEL Data Type: ViBoolean Restrictions: Description: This channel-based attribute specifies whether you want to identify the channel as a source channel. Typically, you set this attribute to VI_TRUE when you attach the channel to a power supply, a function generator, or an active measurement point on the unit under test, and you do not want to connect the channel to another source. The driver prevents source channels from connecting to each other. The pi40iv_connect function returns the PI40IV_ERROR_ATTEMPT_TO_CONNECT_SOURCES when you attempt to connect two channels that you identify as source channels. 24 / 208

29 PI40IV_ATTR_LOGICAL_NAME PI40IV_ATTR_LOGICAL_NAME Data Type: ViString Restrictions: Not settable. Description: A string containing the logical name you specified when opening the current IVI session. You may pass a logical name to the pi40iv_init or pi40iv_initwithoptions functions. The IVI Configuration utility must contain an entry for the logical name. The logical name entry refers to a virtual instrument section in the IVI Configuration file. The virtual instrument section specifies a physical device and initial user options. 25 / 208

30 PI40IV_ATTR_MAX_AC_VOLTAGE PI40IV_ATTR_MAX_AC_VOLTAGE Data Type: ViReal64 Restrictions: Not settable. Description: This channel-based attribute returns the maximum AC voltage the channel can switch. The units are volts RMS. 26 / 208

31 PI40IV_ATTR_MAX_CARRY_AC_CURRENT PI40IV_ATTR_MAX_CARRY_AC_CURRENT Data Type: ViReal64 Restrictions: Not settable. Description: This channel-based attribute returns the maximum AC current the channel can carry. The units are amperes RMS. 27 / 208

32 PI40IV_ATTR_MAX_CARRY_AC_POWER PI40IV_ATTR_MAX_CARRY_AC_POWER Data Type: ViReal64 Restrictions: Not settable. Description: This channel-based attribute returns the maximum AC power the channel can carry. The units are volt-amperes. 28 / 208

33 PI40IV_ATTR_MAX_CARRY_DC_CURRENT PI40IV_ATTR_MAX_CARRY_DC_CURRENT Data Type: ViReal64 Restrictions: Not settable. Description: This channel-based attribute returns the maximum DC current the channel can carry. The units are amperes. 29 / 208

34 PI40IV_ATTR_MAX_CARRY_DC_POWER PI40IV_ATTR_MAX_CARRY_DC_POWER Data Type: ViReal64 Restrictions: Not settable. Description: This channel-based attribute returns the maximum DC power the channel can carry. The units are watts. 30 / 208

35 PI40IV_ATTR_MAX_DC_VOLTAGE PI40IV_ATTR_MAX_DC_VOLTAGE Data Type: ViReal64 Restrictions: Not settable. Description: This channel-based attribute returns the maximum DC voltage the channel can switch. The units are volts. 31 / 208

36 PI40IV_ATTR_MAX_SWITCHING_AC_CURRENT PI40IV_ATTR_MAX_SWITCHING_AC_CURRENT Data Type: ViReal64 Restrictions: Not settable. Description: This channel-based attribute returns the maximum AC current the channel can switch. The units are amperes RMS. 32 / 208

37 PI40IV_ATTR_MAX_SWITCHING_AC_POWER PI40IV_ATTR_MAX_SWITCHING_AC_POWER Data Type: ViReal64 Restrictions: Not settable. Description: This channel-based attribute returns the maximum AC power the channel can switch. The units are volt-amperes. 33 / 208

38 PI40IV_ATTR_MAX_SWITCHING_DC_CURRENT PI40IV_ATTR_MAX_SWITCHING_DC_CURRENT Data Type: ViReal64 Restrictions: Not settable. Description: This channel-based attribute returns the maximum DC current the channel can switch. The units are amperes. 34 / 208

39 PI40IV_ATTR_MAX_SWITCHING_DC_POWER PI40IV_ATTR_MAX_SWITCHING_DC_POWER Data Type: ViReal64 Restrictions: Not settable. Description: This channel-based attribute returns the maximum DC power the channel can switch. The units are watts. 35 / 208

40 PI40IV_ATTR_NUM_OF_COLUMNS PI40IV_ATTR_NUM_OF_COLUMNS Data Type: ViInt32 Restrictions: Not settable. Description: This attribute returns the number of columns of a matrix or scanner. If the switch module is a scanner, this value is the number of input channels. The PI40IV_ATTR_WIRE_MODE attribute affects the number of available columns. For example, if your module has 8 input lines and you use the fourwire mode, then the number of columns you have available is / 208

41 PI40IV_ATTR_NUM_OF_ROWS PI40IV_ATTR_NUM_OF_ROWS Data Type: ViInt32 Restrictions: Not settable. Description: This attribute returns the number of rows of a matrix or scanner. If the switch module is a scanner, this value is the number of output channels. The PI40IV_ATTR_WIRE_MODE attribute affects the number of available rows. For example, if your module has 2 output lines and you use the two-wire mode, then the number of rows you have available is / 208

42 PI40IV_ATTR_PRIMARY_ERROR PI40IV_ATTR_PRIMARY_ERROR (*not needed) Data Type: Restrictions: Description: ViInt32 A code that describes the first error that occurred since the last call to pi40iv_geterrorinfo on the session. The value follows the VXIplug&play completion code conventions. A negative value describes an error condition. A positive value describes a warning condition and indicates that no error occurred. A zero indicates that no error or warning occurred. The error and warning values can be status codes defined by IVI, VISA, class drivers, or specific drivers. 38 / 208

43 PI40IV_ATTR_QUERY_INSTRUMENT_STATUS PI40IV_ATTR_QUERY_INSTRUMENT_STATUS Data Type: Restrictions: Description: ViBoolean Specifies whether the instrument driver queries the instrument status after each operation. Querying the instrument status is very useful for debugging. After you validate your program, you can set this attribute to VI_FALSE to disable status checking and maximize performance The instrument driver can choose to ignore status checking for particular attributes regardless of the setting of this attribute. The default value is VI_TRUE. Use the pi40iv_initwithoptions function to override this value. 39 / 208

44 PI40IV_ATTR_RANGE_CHECK PI40IV_ATTR_RANGE_CHECK Data Type: Restrictions: Description: ViBoolean Specifies whether to validate attribute values and function parameters. If enabled, the instrument driver validates the parameter values that you pass to driver functions. Range checking parameters is very useful for debugging. After you validate your program, you can set this attribute to VI_FALSE to disable range checking and maximize performance. The default value is VI_TRUE. Use the pi40iv_initwithoptions function to override this value. 40 / 208

45 PI40IV_ATTR_RECORD_COERCIONS PI40IV_ATTR_RECORD_COERCIONS Data Type: Restrictions: Description: ViBoolean Specifies whether the IVI engine keeps a list of the value coercions it makes for ViInt32 and ViReal64 attributes. You call pi40iv_getnextcoercionrecord to extract and delete the oldest coercion record from the list. The default value is VI_FALSE. Use the pi40iv_initwithoptions function to override this value. 41 / 208

46 PI40IV_ATTR_SECONDARY_ERROR PI40IV_ATTR_SECONDARY_ERROR (*not needed) Data Type: Restrictions: Description: ViInt32 An optional code that provides additional information concerning the primary error condition. The error and warning values can be status codes defined by IVI, VISA, class drivers, or specific drivers. Zero indicates no additional information. * This function is only needed for the obsolete functions pi40iv_geterrorinfo and pi40iv_clearerrorinfo. 42 / 208

47 PI40IV_ATTR_SETTLING_TIME PI40IV_ATTR_SETTLING_TIME Data Type: Restrictions: Description: ViReal64 This channel-based attribute returns the maximum length of time from after you make a connection until the signal flowing through the channel settles. The units are seconds. 43 / 208

48 PI40IV_ATTR_SIMULATE PI40IV_ATTR_SIMULATE Data Type: Restrictions: Description: ViBoolean Specifies whether or not to simulate instrument driver I/O operations. If simulation is enabled, instrument driver functions perform range checking and call Ivi_GetAttribute and Ivi_SetAttribute functions, but they do not perform instrument I/O. For output parameters that represent instrument data, the instrument driver functions return calculated values. The default value is VI_FALSE. Use the pi40iv_initwithoptions function to override this value. 44 / 208

49 Pickering Interfaces PXI IVI Switch Online PI40IV_ATTR_SPECIFIC_DRIVER_CLASS_SPEC_MAJOR_VERSION Help PI40IV_ATTR_SPECIFIC_DRIVER_CLASS_SPEC_MAJOR_VERSION Data Type: ViInt32 Restrictions: Not settable. Description: The major version number of the class specification with which this driver is compliant. 45 / 208

50 Pickering Interfaces PXI IVI Switch Online PI40IV_ATTR_SPECIFIC_DRIVER_CLASS_SPEC_MINOR_VERSION Help PI40IV_ATTR_SPECIFIC_DRIVER_CLASS_SPEC_MINOR_VERSION Data Type: ViInt32 Restrictions: Not settable. Description: The minor version number of the class specification with which this driver is compliant. 46 / 208

51 PI40IV_ATTR_SPECIFIC_DRIVER_DESCRIPTION PI40IV_ATTR_SPECIFIC_DRIVER_DESCRIPTION Data Type: ViString Restrictions: Not settable. Description: A string that contains a brief description of the specific driver. 47 / 208

52 PI40IV_ATTR_SPECIFIC_DRIVER_MAJOR_VERSION PI40IV_ATTR_SPECIFIC_DRIVER_MAJOR_VERSION Data Type: ViInt32 Restrictions: Not settable. Description: The major version number of this instrument driver. 48 / 208

53 PI40IV_ATTR_SPECIFIC_DRIVER_MINOR_VERSION PI40IV_ATTR_SPECIFIC_DRIVER_MINOR_VERSION Data Type: ViInt32 Restrictions: Not settable. Description: The minor version number of this instrument driver. 49 / 208

54 PI40IV_ATTR_SPECIFIC_DRIVER_PREFIX PI40IV_ATTR_SPECIFIC_DRIVER_PREFIX Data Type: ViString Restrictions: Not settable. Description: A string that contains the prefix for the instrument driver. The name of each user-callable function in this driver starts with this prefix. 50 / 208

55 PI40IV_ATTR_SPECIFIC_DRIVER_REVISION PI40IV_ATTR_SPECIFIC_DRIVER_REVISION Data Type: ViString Restrictions: Not settable. Description: A string that contains additional version information about this instrument driver. 51 / 208

56 PI40IV_ATTR_SPECIFIC_DRIVER_VENDOR PI40IV_ATTR_SPECIFIC_DRIVER_VENDOR Data Type: ViString Restrictions: Not settable. Description: A string that contains the name of the vendor that supplies this driver. 52 / 208

57 PI40IV_ATTR_SUPPORTED_INSTRUMENT_MODELS PI40IV_ATTR_SUPPORTED_INSTRUMENT_MODELS Data Type: ViString Restrictions: Not settable. Description: Contains a model code of the instrument. For drivers that support more than one device, this attribute contains a comma-separated list of supported instrument models. 53 / 208

58 PI40IV_ATTR_WIRE_MODE PI40IV_ATTR_WIRE_MODE Data Type: ViInt32 Restrictions: Not settable. Description: This attribute specifies the wire mode of the switch module. This attribute affects the values of the PI40IV_ATTR_NUM_OF_ROWS and PI40IV_ATTR_NUM_OF_COLUMNS attributes. The actual number of input and output lines on the switch module is fixed, but the number of channels depends on how many lines constitute each channel. 54 / 208

59 PI40IV_ATTR_VXI_MANF_ID PI40IV_ATTR_VXI_MANF_ID Data Type: ViInt32 Restrictions: Not settable. Description: Returns the manufacturer identification number of the VXIbus device. The instrument driver gets the value of this attribute when you pass VI_TRUE for the ID Query parameter to the pi40iv_init or pi40iv_initwithoptions function. 55 / 208

60 PI40IV_ATTR_VXI_MODEL_CODE PI40IV_ATTR_VXI_MODEL_CODE Data Type: ViInt32 Restrictions: Not settable. Description: Returns the model code for the VXIbus device. The instrument driver gets the value of this attribute when you pass VI_TRUE for the ID Query parameter to the pi40iv_init or pi40iv_initwithoptions function. 56 / 208

61 pi40iv_getpath pi40iv_getpath ViStatus pi40iv_getpath (ViSession instrumenthandle, ViChar _VI_FAR channel1[], ViChar _VI_FAR channel2[], ViInt32 buffersize, ViChar _VI_FAR path[]); Purpose In some cases there is more than one possible path between two channels. The driver or the instrument selects the path when you connect two channels with the pi40iv_connect function. Thus, you cannot guarantee that every call to the pi40iv_connect function establishes exactly the same path when you pass the same channels. This function returns a string that uniquely identifies the path you create with the pi40iv_connect function. You can pass this string to the pi40iv_setpath function to establish the exact same path in the future. Note: (1) This function returns only those paths that you explicitly create by calling pi40iv_connect and pi40iv_setpath functions. For example, if you connect channels CH1 and CH3, and then channels CH2 and CH3, the explicit path between channels CH1 and Ch2 does not exist and this function returns an error. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channel1 Variable Type ViChar[] You identify a path with two channels. Pass one of the channel names for which you want to obtain a path. Pass the other channel name as the Channel 2 parameter. Valid Channel Names Default Value: "" channel2 Variable Type ViChar[] You identify a path with two channels. Pass one of the channel names for which you want to obtain a path. Pass the other channel name as the Channel 1 parameter. Valid Channel Names Default Value: "" buffersize Variable Type ViInt32 Pass the number of bytes in the ViChar array you specify for the Path List parameter. If the current value of the attribute, including the terminating NUL byte, contains more bytes that you indicate in this parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "R1->C1" and the Buffer Size is 4, the function places "R1-" into the buffer and returns 7. If you pass 0, you can pass VI_NULL for the Path parameter. This enables you to find out the path size and to allocate the buffer of the appropriate size before calling this function again. path Variable Type ViChar[] 57 / 208

62 The comma-separated path between channels you specify in the Channel 1 and Channel 2 parameters. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. If the current value of the return buffer, including the terminating NUL byte, is larger than the size you indicate in the Buffer Size parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. The general meaning of the status code is as follows: Value Meaning Success Positive Values Warnings Negative Values Errors This driver defines the following status codes: Status Description ERRORS & WARNINGS: Driver error list This instrument driver also returns errors and warnings defined by other sources. The following table defines the ranges of additional status codes that this driver can return. The table lists the different include files that contain the defined constants for the particular status codes: Numeric Range (in Hex) Status Code Types FFA2000 to 3FFA3FFF IviSwtch Warnings 3FFA0000 to 3FFA1FFF IVI Warnings 3FFF0000 to 3FFFFFFF VISA Warnings 3FFC0000 to 3FFCFFFF VXIPnP Driver Warnings BFFA2000 to BFFA3FFF IviSwtch Errors BFFA0000 to BFFA1FFF IVI Errors BFFF0000 to BFFFFFFF VISA Errors BFFC0000 to BFFCFFFF VXIPnP Driver Errors pi40iv_getpath 58 / 208

63 pi40iv_setpath pi40iv_setpath ViStatus pi40iv_setpath (ViSession instrumenthandle, ViChar _VI_FAR pathlist[]); Purpose This function connects two channels by establishing the exact path you specify with the pathlist parameter. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None pathlist Variable Type ViChar[] Pass the path list for the path you previously created that you want the switch module to establish. You obtain the path list for a path you previously created with the pi40iv_getpath function. Example: The path from Ch1 to Ch3 over Conf1 is: "Ch1->Conf1,Conf1->Ch3" Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. The general meaning of the status code is as follows: Value Meaning Success Positive Values Warnings Negative Values Errors This driver defines the following status codes: Status Description ERRORS & WARNINGS: Driver error list This instrument driver also returns errors and warnings defined by other sources. The following table defines the ranges of additional status codes that this driver can return. The table lists the different include files that contain the defined constants for the particular status codes: Numeric Range (in Hex) Status Code Types FFA2000 to 3FFA3FFF IviSwtch Warnings 59 / 208

64 3FFA0000 to 3FFA1FFF IVI Warnings 3FFF0000 to 3FFFFFFF VISA Warnings 3FFC0000 to 3FFCFFFF VXIPnP Driver Warnings BFFA2000 to BFFA3FFF IviSwtch Errors BFFA0000 to BFFA1FFF IVI Errors BFFF0000 to BFFFFFFF VISA Errors BFFC0000 to BFFCFFFF VXIPnP Driver Errors pi40iv_setpath 60 / 208

65 pi40iv_connect pi40iv_connect ViStatus pi40iv_connect (ViSession instrumenthandle, ViChar _VI_FAR channel1[], ViChar _VI_FAR channel2[]); Purpose This function creates a path between Channel 1 and Channel 2. The driver calculates the shortest path between the two channels. If a path is not available, the function returns one of the following errors: PI40IV_ERROR_EXPLICIT_CONNECTION_EXISTS (0xBFFA200C), if the two channels are already explicitly connected by calling either the pi40iv_connect or pi40iv_setpath function. PI40IV_ERROR_IS_CONFIGURATION_CHANNEL (0xBFFA2009), if a channel is a configuration channel. Error elaboration contains information about which of the two channels is a configuration channel. PI40IV_ERROR_ATTEMPT_TO_CONNECT_SOURCES (0xBFFA200B), if both channels are connected to a different source. Error elaboration contains information about sources channel 1 and 2 connect to. PI40IV_ERROR_CANNOT_CONNECT_TO_ITSELF (0xBFFA2015), if channels 1 and 2 are one and the same channel. PI40IV_ERROR_PATH_NOT_FOUND (0xBFFA2011), if the driver cannot find a path between the two channels. Notes: (1) The paths are bidirectional. For example, if a path exists between channels CH1 and CH2, then the path between channels CH2 and CH1 also exists. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channel1 Variable Type ViChar[] You identify a path with two channels. Pass one of the channel names for which you want to create a path. Pass the other channel name as the Channel 2 parameter. Valid Channel Names Default Value: "" channel2 Variable Type ViChar[] You identify a path with two channels. Pass one of the channel names for which you want to create a path. Pass the other channel name as the Channel 1 parameter. Valid Channel Names 61 / 208

66 Default Value: "" pi40iv_connect Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 62 / 208

67 pi40iv_disconnect pi40iv_disconnect ViStatus pi40iv_disconnect (ViSession instrumenthandle, ViChar _VI_FAR channel1[], ViChar _VI_FAR channel2[]); Purpose This function destroys the path between two channels that you create with the pi40iv_connect or pi40iv_setpath function. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channel1 Variable Type ViChar[] You identify a path with two channels. Pass one of the channel names that identify the path you want to destroy. Pass the other channel name as the Channel 2 parameter. Valid Channel Names Default Value: "" channel2 Variable Type ViChar[] You identify a path with two channels. Pass one of the channel names that identify the path you want to destroy. Pass the other channel name as the Channel 1 parameter. Valid Channel Names Default Value: "" Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 63 / 208

68 pi40iv_disconnectall pi40iv_disconnectall ViStatus pi40iv_disconnectall (ViSession instrumenthandle); Purpose This function disconnects all existing paths. Note: If the switch module is not capable of disconnecting all paths, this function returns PI40IV_WARN_PATH_REMAINS (0x3FFA2001) warning. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 64 / 208

69 pi40iv_isdebounced pi40iv_isdebounced ViStatus pi40iv_isdebounced (ViSession instrumenthandle, ViPBoolean isdebounced); Purpose This function returns the state of the switch module. It indicates if all the paths that you created have settled. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None isdebounced Variable Type ViBoolean (passed by reference) Indicates the state of the switch module. The driver returns the value of PI40IV_ATTR_IS_DEBOUNCED attribute. The value VI_TRUE indicates that all the paths that you created have settled. The value VI_FALSE indicates that all the paths that you created have not settled. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 65 / 208

70 pi40iv_canconnect pi40iv_canconnect ViStatus pi40iv_canconnect (ViSession instrumenthandle, ViChar _VI_FAR channel1[], ViChar _VI_FAR channel2[], ViPInt32 pathcapability); Purpose This function verifies that the switch module is capable of creating a path between the two channels you specify with the Channel 1 and Channel 2 parameters. If the switch module is capable of creating a path, this function indicates whether the path is currently available given the existing connections. If the path is not available due to the currently existing connections, but the implicit connection between the two channels already exists, the function returns the PI40IV_WARN_IMPLICIT_CONNECTION_EXISTS (0x3FFA2002) warning. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channel1 Variable Type ViChar[] You identify a path with two channels. Pass one of the channel names for which you want to verify a path. Pass the other channel name as the Channel 2 parameter. Valid Channel Names Default Value: "" channel2 Variable Type ViChar[] You identify a path with two channels. Pass one of the channel names for which you want to verify a path. Pass the other channel name as the Channel 1 parameter. Valid Channel Names Default Value: "" pathcapability Variable Type ViInt32 (passed by reference) Indicates whether a path is valid. Possible values include: Status Name Actual Value PI40IV_VAL_PATH_AVAILABLE 1 PI40IV_VAL_PATH_EXISTS 2 PI40IV_VAL_PATH_UNSUPPORTED 3 PI40IV_VAL_RSRC_IN_USE 4 PI40IV_VAL_SOURCE_CONFLICT 5 PI40IV_VAL_CHANNEL_NOT_AVAILABLE 6 Notes: (1) PI40IV_VAL_PATH_AVAILABLE indicates that the driver can create the path at this time. (2) PI40IV_VAL_PATH_EXISTS indicates that the path already exists. (3) PI40IV_VAL_PATH_UNSUPPORTED indicates that the instrument is not capable of 66 / 208

71 pi40iv_canconnect creating a path between the channels you specify. (4) PI40IV_VAL_RSRC_IN_USE indicates that although the path is valid, the driver cannot create the path at this moment because the switch module is currently using one or more of the required channels to create another path. You must destroy the other path before creating this one. (5) PI40IV_VAL_SOURCE_CONFLICT indicates that the instrument cannot create a path because both channels are connected to a different source channel. (6) PI40IV_VAL_CHANNEL_NOT_AVAILABLE indicates that the driver cannot create a path between the two channels because one of the channels is a configuration channel and thus unavailable for external connections. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 67 / 208

72 pi40iv_waitfordebounce pi40iv_waitfordebounce ViStatus pi40iv_waitfordebounce (ViSession instrumenthandle, ViInt32 maximumtime_ms); Purpose This function returns after all the paths that you create have settled. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None maximumtime_ms Variable Type ViInt32 Specifies the maximum length of time for this function to wait until all switches in the switch module debounce. If the time you specify elapses before all switches debounce, this function returns a timeout error. The units are milliseconds. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 68 / 208

73 pi40iv_getattributeviboolean pi40iv_getattributeviboolean ViStatus pi40iv_getattributeviboolean (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViPBoolean attributevalue); Purpose This function queries the value of a ViBoolean attribute. You can use this function to get the values of instrument - specific attributes and inherent IVI attributes. If the attribute represents an instrument state, this function performs instrument I/O in the following cases: - State caching is disabled for the entire session or for the particular attribute. - State caching is enabled and the currently cached value is invalid. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to obtain the value of the attribute. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViBoolean type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViBoolean are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel for the corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViBoolean (passed by reference) Returns the current value of the attribute. Pass the address of a ViBoolean variable. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has named constants 69 / 208

74 pi40iv_getattributeviboolean as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then pressing <ENTER>. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 70 / 208

75 pi40iv_getattributeviint32 pi40iv_getattributeviint32 ViStatus pi40iv_getattributeviint32 (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViPInt32 attributevalue); Purpose This function queries the value of a ViInt32 attribute. You can use this function to get the values of instrument- specific attributes and inherent IVI attributes. If the attribute represents an instrument state, this function performs instrument I/O in the following cases: - State caching is disabled for the entire session or for the particular attribute. - State caching is enabled and the currently cached value is invalid. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to obtain the value of the attribute. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViInt32 type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViInt32 are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel for the corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViInt32 (passed by reference) Returns the current value of the attribute. Pass the address of a ViInt32 variable. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has named constants 71 / 208

76 as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then pressing <ENTER>. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. pi40iv_getattributeviint32 72 / 208

77 pi40iv_getattributevireal64 pi40iv_getattributevireal64 ViStatus pi40iv_getattributevireal64 (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViPReal64 attributevalue); Purpose This function queries the value of a ViReal64 attribute. You can use this function to get the values of instrument- specific attributes and inherent IVI attributes. If the attribute represents an instrument state, this function performs instrument I/O in the following cases: - State caching is disabled for the entire session or for the particular attribute. - State caching is enabled and the currently cached value is invalid. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to obtain the value of the attribute. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViReal64 type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViReal64 are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel for the corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViReal64 (passed by reference) Returns the current value of the attribute. Pass the address of a ViReal64 variable. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has named constants 73 / 208

78 pi40iv_getattributevireal64 as valid values, you can view a list of the constants by pressing <ENTER> on this control.select a value by double-clicking on it or by selecting it and then pressing <ENTER>. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 74 / 208

79 pi40iv_getattributevisession pi40iv_getattributevisession ViStatus pi40iv_getattributevisession (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViPSession attributevalue); Purpose This function queries the value of a ViSession attribute. You can use this function to get the values of instrument- specific attributes and inherent IVI attributes. If the attribute represents an instrument state, this function performs instrument I/O in the following cases: - State caching is disabled for the entire session or for the particular attribute. - State caching is enabled and the currently cached value is invalid. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to obtain the value of the attribute. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViSession type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViSession are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel for the corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViSession (passed by reference) Returns the current value of the attribute. Pass the address of a ViSession variable. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has named constants 75 / 208

80 pi40iv_getattributevisession as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then pressing <ENTER>. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 76 / 208

81 pi40iv_getattributevistring pi40iv_getattributevistring ViStatus pi40iv_getattributevistring (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViInt32 buffersize, ViChar _VI_FAR attributevalue[]); Purpose This function queries the value of a ViString attribute. You can use this function to get the values of instrument- specific attributes and inherent IVI attributes. If the attribute represents an instrument state, this function performs instrument I/O in the following cases: - State caching is disabled for the entire session or for the particular attribute. - State caching is enabled and the currently cached value is invalid. You must provide a ViChar array to serve as a buffer for the value. You pass the number of bytes in the buffer as the Buffer Size parameter. If the current value of the attribute, including the terminating NUL byte, is larger than the size you indicate in the Buffer Size parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. If you want to call this function just to get the required buffer size, you can pass 0 for the Buffer Size and VI_NULL for the Attribute Value buffer. If you want the function to fill in the buffer regardless of the number of bytes in the value, pass a negative number for the Buffer Size parameter. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to obtain the value of the attribute. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names: x1,x2,y1,y2 Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViString type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViString are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel 77 / 208

82 for the corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. buffersize Variable Type ViInt32 Pass the number of bytes in the ViChar array you specify for the Attribute Value parameter. If the current value of the attribute, including the terminating NUL byte, contains more bytes that you indicate in this parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. If you pass a negative number, the function copies the value to the buffer regardless of the number of bytes in the value. If you pass 0, you can pass VI_NULL for the Attribute Value buffer parameter. Default Value: 512 pi40iv_getattributevistring attributevalue Variable Type ViChar[] The buffer in which the function returns the current value of the attribute. The buffer must be of type ViChar and have at least as many bytes as indicated in the Buffer Size parameter. If the current value of the attribute, including the terminating NUL byte, contains more bytes that you indicate in this parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. If you specify 0 for the Buffer Size parameter, you can pass VI_NULL for this parameter. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has named constants as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then pressing <ENTER>. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. If the current value of the return buffer, including the terminating NUL byte, is larger than the size you indicate in the Buffer Size parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 78 / 208

83 pi40iv_checkattributeviboolean pi40iv_checkattributeviboolean ViStatus pi40iv_checkattributeviboolean (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViBoolean attributevalue); Purpose This function checks the validity of a value you specify for a ViBoolean attribute. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to check the attribute value. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Attributes whose value cannot be set are dim. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. Readonly attributes appear dim in the list box. If you select a read-only attribute, an error message appears. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViBoolean type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViBoolean are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel for the corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViBoolean Pass the value which you want to verify as a valid value for the attribute. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has constants as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then pressing <ENTER>. Note: Some of the values might not be valid depending on the current settings of the 79 / 208

84 instrument session. Default Value: none pi40iv_checkattributeviboolean Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 80 / 208

85 pi40iv_checkattributeviint32 pi40iv_checkattributeviint32 ViStatus pi40iv_checkattributeviint32 (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViInt32 attributevalue); Purpose This function checks the validity of a value you specify for a ViInt32 attribute. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to check the attribute value. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Attributes whose value cannot be set are dim. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. Read-only attributes appear dim in the list box. If you select a read-only attribute, an error message appears. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViInt32 type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViInt32 are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel for the corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViInt32 Pass the value which you want to verify as a valid value for the attribute. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has constants as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then pressing <ENTER>. 81 / 208

86 pi40iv_checkattributeviint32 Note: Some of the values might not be valid depending on the current settings of the instrument session. Default Value: none Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 82 / 208

87 pi40iv_checkattributevireal64 pi40iv_checkattributevireal64 ViStatus pi40iv_checkattributevireal64 (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViReal64 attributevalue); Purpose This function checks the validity of a value you specify for a ViReal64 attribute. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to check the attribute value. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Attributes whose value cannot be set are dim. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. Readonly attributes appear dim in the list box. If you select a read-only attribute, an error message appears. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViReal64 type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViReal64 are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel for the corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViReal64 Pass the value which you want to verify as a valid value for the attribute. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has constants as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then 83 / 208

88 pi40iv_checkattributevireal64 pressing <ENTER>. Note: Some of the values might not be valid depending on the current settings of the instrument session. Default Value: none Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 84 / 208

89 pi40iv_checkattributevisession pi40iv_checkattributevisession ViStatus pi40iv_checkattributevisession (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViSession attributevalue); Purpose This function checks the validity of a value you specify for a ViSession attribute. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to check the attribute value. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Attributes whose value cannot be set are dim. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. Readonly attributes appear dim in the list box. If you select a read-only attribute, an error message appears. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViSession type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViSession are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel for the corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViSession Pass the value which you want to verify as a valid value for the attribute. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has constants as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then pressing <ENTER>. 85 / 208

90 pi40iv_checkattributevisession Note: Some of the values might not be valid depending on the current settings of the instrument session. Default Value: none Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 86 / 208

91 pi40iv_checkattributevistring pi40iv_checkattributevistring ViStatus pi40iv_checkattributevistring (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViChar _VI_FAR attributevalue[]); Purpose This function checks the validity of a value you specify for a ViString attribute. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to check the attribute value. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Attributes whose value cannot be set are dim. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. Readonly attributes appear dim in the list box. If you select a read-only attribute, an error message appears. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViString type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViString are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel for the corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViChar[] Pass the value which you want to verify as a valid value for the attribute. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has constants as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then pressing <ENTER>. 87 / 208

92 pi40iv_checkattributevistring Note: Some of the values might not be valid depending on the current settings of the instrument session. Default Value: none Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 88 / 208

93 pi40iv_setattributeviboolean pi40iv_setattributeviboolean ViStatus pi40iv_setattributeviboolean (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViBoolean attributevalue); Purpose This function sets the value of a ViBoolean attribute. This is a low-level function that you can use to set the values of instrument-specific attributes and inherent IVI attributes. If the attribute represents an instrument state, this function performs instrument I/O in the following cases: - State caching is disabled for the entire session or for the particular attribute. - State caching is enabled and the currently cached value is invalid or is different than the value you specify. This instrument driver contains high-level functions that set most of the instrument attributes. It is best to use the high-level driver functions as much as possible. They handle order dependencies and multithread locking for you. In addition, they perform status checking only after setting all of the attributes. In contrast, when you set multiple attributes using the SetAttribute functions, the functions check the instrument status after each call. Also, when state caching is enabled, the high-level functions that configure multiple attributes perform instrument I/O only for the attributes whose value you change. Thus, you can safely call the high-level functions without the penalty of redundant instrument I/O. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to set the value of the attribute. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Attributes whose value cannot be set are dim. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. Read-only attributes appear dim in the list box. If you select a read-only attribute, an error message appears. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViBoolean type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViBoolean are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel for the corresponding function that is consistent with 89 / 208

94 pi40iv_setattributeviboolean the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViBoolean Pass the value to which you want to set the attribute. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has constants as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then pressing <ENTER>. Note: Some of the values might not be valid depending on the current settings of the instrument session. Default Value: none Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 90 / 208

95 pi40iv_setattributeviint32 pi40iv_setattributeviint32 ViStatus pi40iv_setattributeviint32 (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViInt32 attributevalue); Purpose This function sets the value of a ViInt32 attribute. This is a low-level function that you can use to set the values of instrument-specific attributes and inherent IVI attributes. If the attribute represents an instrument state, this function performs instrument I/O in the following cases: - State caching is disabled for the entire session or for the particular attribute. - State caching is enabled and the currently cached value is invalid or is different than the value you specify. This instrument driver contains high-level functions that set most of the instrument attributes. It is best to use the high-level driver functions as much as possible. They handle order dependencies and multithread locking for you. In addition, they perform status checking only after setting all of the attributes. In contrast, when you set multiple attributes using the SetAttribute functions, the functions check the instrument status after each call. Also, when state caching is enabled, the high-level functions that configure multiple attributes perform instrument I/O only for the attributes whose value you change. Thus, you can safely call the high-level functions without the penalty of redundant instrument I/O. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to set the value of the attribute. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Attributes whose value cannot be set are dim. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. Readonly attributes appear dim in the list box. If you select a read-only attribute, an error message appears. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViInt32 type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViInt32 are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel for the 91 / 208

96 pi40iv_setattributeviint32 corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViInt32 Pass the value to which you want to set the attribute. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has constants as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then pressing <ENTER>. Note: Some of the values might not be valid depending on the current settings of the instrument session. Default Value: none Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 92 / 208

97 pi40iv_setattributevireal64 pi40iv_setattributevireal64 ViStatus pi40iv_setattributevireal64 (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViReal64 attributevalue); Purpose This function sets the value of a ViReal64 attribute. This is a low-level function that you can use to set the values of instrument-specific attributes and inherent IVI attributes. If the attribute represents an instrument state, this function performs instrument I/O in the following cases: - State caching is disabled for the entire session or for the particular attribute. - State caching is enabled and the currently cached value is invalid or is different than the value you specify. This instrument driver contains high-level functions that set most of the instrument attributes. It is best to use the high-level driver functions as much as possible. They handle order dependencies and multithread locking for you. In addition, they perform status checking only after setting all of the attributes. In contrast, when you set multiple attributes using the SetAttribute functions, the functions check the instrument status after each call. Also, when state caching is enabled, the high-level functions that configure multiple attributes perform instrument I/O only for the attributes whose value you change. Thus, you can safely call the high-level functions without the penalty of redundant instrument I/O. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to set the value of the attribute. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Attributes whose value cannot be set are dim. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. Readonly attributes appear dim in the list box. If you select a read-only attribute, an error message appears. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViReal64 type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViReal64 are dim. If you select an attribute data 93 / 208

98 pi40iv_setattributevireal64 type that is dim, LabWindows/CVI transfers you to the function panel for the corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViReal64 Pass the value to which you want to set the attribute. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has constants as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then pressing <ENTER>. Note: Some of the values might not be valid depending on the current settings of the instrument session. Default Value: none Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 94 / 208

99 pi40iv_setattributevisession pi40iv_setattributevisession ViStatus pi40iv_setattributevisession (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViSession attributevalue); Purpose This function sets the value of a ViSession attribute. This is a low-level function that you can use to set the values of instrument-specific attributes and inherent IVI attributes. If the attribute represents an instrument state, this function performs instrument I/O in the following cases: - State caching is disabled for the entire session or for the particular attribute. - State caching is enabled and the currently cached value is invalid or is different than the value you specify. This instrument driver contains high-level functions that set most of the instrument attributes. It is best to use the high-level driver functions as much as possible. They handle order dependencies and multithread locking for you. In addition, they perform status checking only after setting all of the attributes. In contrast, when you set multiple attributes using the SetAttribute functions, the functions check the instrument status after each call. Also, when state caching is enabled, the high-level functions that configure multiple attributes perform instrument I/O only for the attributes whose value you change. Thus, you can safely call the high-level functions without the penalty of redundant instrument I/O. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to set the value of the attribute. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Attributes whose value cannot be set are dim. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. Read-only attributes appear dim in the list box. If you select a read-only attribute, an error message appears. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViSession type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViSession are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel 95 / 208

100 pi40iv_setattributevisession for the corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViSession Pass the value to which you want to set the attribute. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has constants as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then pressing <ENTER>. Note: Some of the values might not be valid depending on the current settings of the instrument session. Default Value: none Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 96 / 208

101 pi40iv_setattributevistring pi40iv_setattributevistring ViStatus pi40iv_setattributevistring (ViSession instrumenthandle, ViChar _VI_FAR channelname[], ViAttr attributeid, ViChar _VI_FAR attributevalue[]); Purpose This function sets the value of a ViString attribute. This is a low-level function that you can use to set the values of instrument-specific attributes and inherent IVI attributes. If the attribute represents an instrument state, this function performs instrument I/O in the following cases: - State caching is disabled for the entire session or for the particular attribute. - State caching is enabled and the currently cached value is invalid or is different than the value you specify. This instrument driver contains high-level functions that set most of the instrument attributes. It is best to use the high-level driver functions as much as possible. They handle order dependencies and multithread locking for you. In addition, they perform status checking only after setting all of the attributes. In contrast, when you set multiple attributes using the SetAttribute functions, the functions check the instrument status after each call. Also, when state caching is enabled, the high-level functions that configure multiple attributes perform instrument I/O only for the attributes whose value you change. Thus, you can safely call the high-level functions without the penalty of redundant instrument I/O. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None channelname Variable Type ViChar[] If the attribute is channel-based, this parameter specifies the name of the channel on which to set the value of the attribute. If the attribute is not channel-based, then pass VI_NULL or an empty string. Valid Channel Names Default Value: "" attributeid Variable Type ViAttr Attribute List Pass the ID of an attribute. From the function panel window, you can use this control as follows. - Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Attributes whose value cannot be set are dim. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. Read-only attributes appear dim in the list box. If you select a read-only attribute, an error message appears. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViString type. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. Attributes with data types other than ViString are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel for the 97 / 208

102 pi40iv_setattributevistring corresponding function that is consistent with the data type. - If you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. - If the attribute in this ring control has named constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>. attributevalue Variable Type ViChar[] Pass the value to which you want to set the attribute. From the function panel window, you can use this control as follows. - If the attribute currently showing in the Attribute ID ring control has constants as valid values, you can view a list of the constants by pressing <ENTER> on this control. Select a value by double-clicking on it or by selecting it and then pressing <ENTER>. Note: Some of the values might not be valid depending on the current settings of the instrument session. Default Value: none Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 98 / 208

103 pi40iv_geterror pi40iv_geterror ViStatus pi40iv_geterror (ViSession instrumenthandle, ViStatus *errorcode, ViInt32 buffersize, ViChar description[]); Purpose This function retrieves and then clears the IVI error information for the session or the current execution thread. One exception exists: If the BufferSize parameter is 0, the function does not clear the error information. By passing 0 for the buffer size, the caller can ascertain the buffer size required to get the entire error description string and then call the function again with a sufficiently large buffer. If the user specifies a valid IVI session for the InstrumentHandle parameter, Get Error retrieves and then clears the error information for the session. If the user passes VI_NULL for the InstrumentHandle parameter, this function retrieves and then clears the error information for the current execution thread. If the InstrumentHandle parameter is an invalid session, the function does nothing and returns an error. Normally, the error information describes the first error that occurred since the user last called pi40iv_geterror or pi40iv_clearerror. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None errorcode Variable Type ViStatus Returns the error code for the session or execution thread. If you pass 0 for the Buffer Size, you can pass VI_NULL for this parameter. buffersize Variable Type ViInt32 Pass the number of bytes in the ViChar array you specify for the Description parameter. If the error description, including the terminating NUL byte, contains more bytes than you indicate in this parameter, the function copies BufferSize - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. If you pass a negative number, the function copies the value to the buffer regardless of the number of bytes in the value. If you pass 0, you can pass VI_NULL for the Description buffer parameter. Default Value: None description Variable Type ViChar[] Returns the error description for the IVI session or execution thread. 99 / 208

104 If there is no description, the function returns an empty string. pi40iv_geterror The buffer must contain at least as many elements as the value you specify with the Buffer Size parameter. If the error description, including the terminating NUL byte, contains more bytes than you indicate with the Buffer Size parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. If you pass 0 for the Buffer Size, you can pass VI_NULL for this parameter. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 100 / 208

105 pi40iv_clearerror pi40iv_clearerror ViStatus pi40iv_clearerror (ViSession instrumenthandle); Purpose This function clears the error code and error description for the IVI session. If the user specifies a valid IVI session for the instrument_handle parameter, this function clears the error information for the session. If the user passes VI_NULL for the Vi parameter, this function clears the error information for the current execution thread. If the Vi parameter is an invalid session, the function does nothing and returns an error. The function clears the error code by setting it to VI_SUCCESS. If the error description string is non-null, the function de-allocates the error description string and sets the address to VI_NULL. Maintaining the error information separately for each thread is useful if the user does not have a session handle to pass to the pi40iv_geterror function, which occurs when a call to pi40iv_init or pi40iv_initwithoptions fails. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 101 / 208

106 pi40iv_getnextcoercionrecord pi40iv_getnextcoercionrecord ViStatus pi40iv_getnextcoercionrecord (ViSession instrumenthandle, ViInt32 buffersize, ViChar _VI_FAR coercionrecord[]); Purpose This function returns the coercion information associated with the IVI session. This function retrieves and clears the oldest instance in which the instrument driver coerced a value you specified to another value. If you set the PI40IV_ATTR_RECORD_COERCIONS attribute to VI_TRUE, the instrument driver keeps a list of all coercions it makes on ViInt32 or ViReal64 values you pass to instrument driver functions. You use this function to retrieve information from that list. If the next coercion record string, including the terminating NUL byte, contains more bytes than you indicate in this parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. If you pass a negative number, the function copies the value to the buffer regardless of the number of bytes in the value. If you pass 0, you can pass VI_NULL for the Coercion Record buffer parameter. The function returns an empty string in the Coercion Record parameter if no coercion records remain for the session. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init function. The handle identifies a particular instrument session. Default Value: None buffersize Variable Type ViInt32 Pass the number of bytes in the ViChar array you specify for the Coercion Record parameter. If the next coercion record string, including the terminating NUL byte, contains more bytes than you indicate in this parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. If you pass a negative number, the function copies the value to the buffer regardless of the number of bytes in the value. If you pass 0, you can pass VI_NULL for the Coercion Record buffer parameter. Default Value: None coercionrecord Variable Type ViChar[] Returns the next coercion record for the IVI session. If there are no coercion records, the function returns an empty string. The buffer must contain at least as many elements as the value you specify with the Buffer Size parameter. If the next coercion record string, including the terminating NUL byte, contains more bytes than you indicate with the Buffer Size parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you 102 / 208

107 pi40iv_getnextcoercionrecord must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. This parameter returns an empty string if no coercion records remain for the session. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. If the current value of the return buffer, including the terminating NUL byte, is larger than the size you indicate in the Buffer Size parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 103 / 208

108 pi40iv_readinstrdata pi40iv_readinstrdata ViStatus pi40iv_readinstrdata (ViSession instrumenthandle, ViInt32 number_ofbytestoread, ViChar _VI_FAR readbuffer[], ViPInt32 numbytesread); Purpose This function reads data from the instrument. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None number_ofbytestoread Variable Type ViInt32 Pass the maximum number of bytes to read from the instruments. Default Value: 0 Valid Range: 0 to the number of elements in the Read Buffer. readbuffer Variable Type ViChar[] After this function executes, this parameter contains the data that was read from the instrument. numbytesread Variable Type ViInt32 (passed by reference) Returns the number of bytes actually read from the instrument and stored in the Read Buffer. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 104 / 208

109 pi40iv_writeinstrdata pi40iv_writeinstrdata ViStatus pi40iv_writeinstrdata (ViSession instrumenthandle, ViChar _VI_FAR writebuffer[]); Purpose This function writes a user-specified string to the instrument. Note: This function bypasses IVI attribute state caching. Therefore, when you call this function, the cached values for all attributes will be invalidated. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None writebuffer Variable Type ViChar[] Pass the string to be written to the instrument. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 105 / 208

110 pi40iv_locksession pi40iv_locksession ViStatus pi40iv_locksession (ViSession instrumenthandle, ViPBoolean callerhaslock); Purpose This function obtains a multithread lock on the instrument session. Before it does so, it waits until all other execution threads have released their locks on the instrument session. Other threads might have obtained a lock on this session in the following ways: - The user's application called pi40iv_locksession. - A call to the instrument driver locked the session. - A call to the IVI engine locked the session. After your call to pi40iv_locksession returns successfully, no other threads can access the instrument session until you call pi40iv_unlocksession. Use pi40iv_locksession and pi40iv_unlocksession around a sequence of calls to instrument driver functions if you require that the instrument retain its settings through the end of the sequence. You can safely make nested calls to pi40iv_locksession within the same thread. To completely unlock the session, you must balance each call to pi40iv_locksession with a call to pi40iv_unlocksession. If, however, you use the Caller Has Lock parameter in all calls to pi40iv_locksession and pi40iv_unlocksession within a function, the IVI Library locks the session only once within the function regardless of the number of calls you make to pi40iv_locksession. This allows you to call pi40iv_unlocksession just once at the end of the function. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None callerhaslock Variable Type ViBoolean (passed by reference) This parameter serves as a convenience. If you do not want to use this parameter, pass VI_NULL. Use this parameter in complex functions to keep track of whether you obtain a lock and therefore need to unlock the session. Pass the address of a local ViBoolean variable. In the declaration of the local variable, initialize it to VI_FALSE. Pass the address of the same local variable to any other calls you make to pi40iv_locksession or pi40iv_unlocksession in the same function. The parameter is an input/output parameter. pi40iv_locksession and pi40iv_unlocksession each inspect the current value and take the following actions: - If the value is VI_TRUE, pi40iv_locksession does not lock the session again. If the value is VI_FALSE, pi40iv_locksession obtains the lock and sets the value of the parameter to VI_TRUE. - If the value is VI_FALSE, pi40iv_unlocksession does not attempt to unlock the session. If the value is VI_TRUE, pi40iv_unlocksession releases the lock and sets the value of the parameter to VI_FALSE. Thus, you can, call pi40iv_unlocksession at the end of your function without worrying about whether you actually have the lock. Example: 106 / 208

111 ViStatus TestFunc (ViSession vi, ViInt32 flags) { ViStatus error = VI_SUCCESS; ViBoolean havelock = VI_FALSE; if (flags & BIT_1) { vicheckerr( pi40iv_locksession(vi, &havelock)); vicheckerr( TakeAction1(vi)); if (flags & BIT_2) { vicheckerr( pi40iv_unlocksession(vi, &havelock)); vicheckerr( TakeAction2(vi)); vicheckerr( pi40iv_locksession(vi, &havelock); } if (flags & BIT_3) vicheckerr( TakeAction3(vi)); } Error: /* At this point, you cannot really be sure that you have the lock. Fortunately, the havelock variable takes care of that for you. */ pi40iv_unlocksession(vi, &havelock); return error; } pi40iv_locksession Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 107 / 208

112 pi40iv_unlocksession pi40iv_unlocksession ViStatus pi40iv_unlocksession (ViSession instrumenthandle, ViPBoolean callerhaslock); Purpose This function releases a lock that you acquired on an instrument session using pi40iv_locksession. Refer to pi40iv_locksession for additional information on session locks. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None callerhaslock Variable Type ViBoolean (passed by reference) This parameter serves as a convenience. If you do not want to use this parameter, pass VI_NULL. Use this parameter in complex functions to keep track of whether you obtain a lock and therefore need to unlock the session. Pass the address of a local ViBoolean variable. In the declaration of the local variable, initialize it to VI_FALSE. Pass the address of the same local variable to any other calls you make to pi40iv_locksession or pi40iv_unlocksession in the same function. The parameter is an input/output parameter. pi40iv_locksession and pi40iv_unlocksession each inspect the current value and take the following actions: - If the value is VI_TRUE, pi40iv_locksession does not lock the session again. If the value is VI_FALSE, pi40iv_locksession obtains the lock and sets the value of the parameter to VI_TRUE. - If the value is VI_FALSE, pi40iv_unlocksession does not attempt to unlock the session. If the value is VI_TRUE, pi40iv_unlocksession releases the lock and sets the value of the parameter to VI_FALSE. Thus, you can, call pi40iv_unlocksession at the end of your function without worrying about whether you actually have the lock. Example: ViStatus TestFunc (ViSession vi, ViInt32 flags) { ViStatus error = VI_SUCCESS; ViBoolean havelock = VI_FALSE; if (flags & BIT_1) { vicheckerr( pi40iv_locksession(vi, &havelock)); vicheckerr( TakeAction1(vi)); if (flags & BIT_2) { vicheckerr( pi40iv_unlocksession(vi, &havelock)); vicheckerr( TakeAction2(vi)); vicheckerr( pi40iv_locksession(vi, &havelock); } if (flags & BIT_3) vicheckerr( TakeAction3(vi)); } Error: 108 / 208

113 /* At this point, you cannot really be sure that you have the lock. Fortunately, the havelock variable takes care of that for you. */ pi40iv_unlocksession(vi, &havelock); return error; } pi40iv_unlocksession Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 109 / 208

114 pi40iv_getnextinterchangewarning pi40iv_getnextinterchangewarning ViStatus pi40iv_getnextinterchangewarning(visession instrumenthandle, ViInt32 buffersize, ViChar warnstring[]) Purpose This function returns the interchangeability warnings associated with the IVI session. It retrieves and clears the oldest instance in which the class driver recorded an interchangeability warning. Interchangeability warnings indicate that using your application with a different instrument might cause different behavior. You use this function to retrieve interchangeability warnings. The driver performs interchangeability checking when the PI40IV_ATTR_INTERCHANGE_CHECK attribute is set to VI_TRUE. The function returns an empty string in the Interchange Warning parameter if no interchangeability warnings remain for the session. In general, the instrument driver generates interchangeability warnings when an attribute that affects the behavior of the instrument is in a state that you did not specify. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None buffersize Variable Type ViInt32 Pass the number of bytes in the ViChar array you specify for the Interchange Warning parameter. If the next interchangeability warning string, including the terminating NUL byte, contains more bytes than you indicate in this parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. If you pass a negative number, the function copies the value to the buffer regardless of the number of bytes in the value. If you pass 0, you can pass VI_NULL for the Interchange Warning buffer parameter. Default Value: None warnstring Variable Type ViChar[] Returns the next interchange warning for the IVI session. If there are no interchange warnings, the function returns an empty string. The buffer must contain at least as many elements as the value you specify with the Buffer Size parameter. If the next interchangeability warning string, including the terminating NUL byte, contains more bytes than you indicate with the Buffer Size parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL 110 / 208

115 pi40iv_getnextinterchangewarning byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. This parameter returns an empty string if no interchangeability warnings remain for the session. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 111 / 208

116 pi40iv_clearinterchangewarning pi40iv_clearinterchangewarning ViStatus pi40iv_clearinterchangewarning(visession instrumenthandle) Purpose This function clears the list of current interchange warnings. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 112 / 208

117 pi40iv_resetinterchangecheck pi40iv_resetinterchangecheck ViStatus pi40iv_resetinterchangecheck(visession instrumenthandle) Purpose When developing a complex test system that consists of multiple test modules, it is generally a good idea to design the test modules so that they can run in any order. To do so requires ensuring that each test module completely configures the state of each instrument it uses. If a particular test module does not completely configure the state of an instrument, the state of the instrument depends on the configuration from a previously executed test module. If you execute the test modules in a different order, the behavior of the instrument and therefore the entire test module is likely to change. This change in behavior is generally instrument specific and represents an interchangeability problem. You can use this function to test for such cases. After you call this function, the interchangeability checking algorithms in the specific driver ignore all previous configuration operations. By calling this function at the beginning of a test module, you can determine whether the test module has dependencies on the operation of previously executed test modules. This function does not clear the interchangeability warnings from the list of previously recorded interchangeability warnings. If you want to guarantee that the pi40iv_getnextinterchangewarning function only returns those interchangeability warnings that are generated after calling this function, you must clear the list of interchangeability warnings. You can clear the interchangeability warnings list by repeatedly calling the pi40iv_getnextinterchangewarning function until no more interchangeability warnings are returned. If you are not interested in the content of those warnings, you can call the pi40iv_clearinterchangewarnings function. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 113 / 208

118 pi40iv_error_message pi40iv_error_message ViStatus pi40iv_error_message (ViSession instrumenthandle, ViStatus errorcode, ViChar _VI_FAR errormessage[]); Purpose This function converts a status code returned by an instrument driver function into a userreadable string. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. You can pass VI_NULL for this parameter. This is useful when one of the initialize functions fail. Default Value: VI_NULL errorcode Variable Type ViStatus Pass the Status parameter that is returned from any of the instrument driver functions. Default Value: 0 (VI_SUCCESS) pi40iv Status Codes: Status Description ERRORS & WARNINGS: Driver error list IviSwtch Status Codes: Status Description WARNINGS: 3FFA2001 Some connections remain after disconnecting. 3FFA2002 The channels are implicitly connected. ERRORS: BFFA2001 Invalid path string. BFFA2002 Invalid Scan List string. BFFA2003 One of the channels is in use. BFFA2004 The scan list string is empty. BFFA2005 The path string is empty. BFFA2006 The switch module is currently in scanning mode. BFFA2007 The switch module is not currently in scanning mode. BFFA2008 No explicit path exists between the two channels. BFFA2009 Cannot explicitly connect a configuration channel. BFFA200A One path channel is not a configuration channel. BFFA200B Cannot connect two sources. BFFA200C The channels are explicitly connected. BFFA200D A leg in the path does not begin with a channel name. BFFA200E A leg in the path is missing the second channel name. 114 / 208

119 BFFA200F The first and second channels in the leg are the same. BFFA2010 Duplicate channel in the path string. BFFA2011 No path found between the channels. BFFA2012 Beginning and end of adjacent legs are not the same. BFFA2013 Path contains a leg with un-connectable channels. BFFA2014 A leg in the path is already connected. BFFA2015 A channel cannot be connected to itself. pi40iv_error_message IVI Engine Status Codes: Status Description ERRORS: BFFA0001 Instrument error. Call pi40iv_error_query. BFFA0002 Cannot open file. BFFA0003 Error reading from file. BFFA0004 Error writing to file. BFFA0005 Driver module file not found. BFFA0006 Cannot open driver module file for reading. BFFA0007 Driver module has invalid file format or invalid data. BFFA0008 Driver module contains undefined references. BFFA0009 Cannot find function in driver module. BFFA000A Failure loading driver module. BFFA000B Invalid path name. BFFA000C Invalid attribute. BFFA000D IVI attribute is not writable. BFFA000E IVI attribute is not readable. BFFA000F Invalid parameter. BFFA0010 Invalid value. BFFA0011 Function not supported. BFFA0012 Attribute not supported. BFFA0013 Value not supported. BFFA0014 Invalid type. BFFA0015 Types do not match. BFFA0016 Attribute already has a value waiting to be updated. BFFA0017 Specified item already exists. BFFA0018 Not a valid configuration. BFFA0019 Requested item does not exist or value not available. BFFA001A Requested attribute value not known. BFFA001B No range table. BFFA001C Range table is invalid. BFFA001D Object or item is not initialized. BFFA001E Non-interchangeable behavior. BFFA001F No channel table has been built for the session. BFFA0020 Channel name specified is not valid. BFFA0021 Unable to allocate system resource. BFFA0022 Permission to access file was denied. BFFA0023 Too many files are already open. BFFA0024 Unable to create temporary file in target directory. BFFA0025 All temporary filenames already used. BFFA0026 Disk is full. BFFA0027 Cannot find configuration file on disk. BFFA0028 Cannot open configuration file. BFFA0029 Error reading configuration file. BFFA002A Invalid ViInt32 value in configuration file. BFFA002B Invalid ViReal64 value in configuration file. 115 / 208

120 BFFA002C Invalid ViBoolean value in configuration file. BFFA002D Entry missing from configuration file. BFFA002E Initialization failed in driver DLL. BFFA002F Driver module has unresolved external reference. BFFA0030 Cannot find CVI Run-Time Engine. BFFA0031 Cannot open CVI Run-Time Engine. BFFA0032 CVI Run-Time Engine has invalid format. BFFA0033 CVI Run-Time Engine is missing required function(s). BFFA0034 CVI Run-Time Engine initialization failed. BFFA0035 CVI Run-Time Engine has unresolved external reference. BFFA0036 Failure loading CVI Run-Time Engine. BFFA0037 Cannot open DLL for read exports. BFFA0038 DLL file is corrupt. BFFA0039 No DLL export table in DLL. BFFA003A Unknown attribute name in default configuration file. BFFA003B Unknown attribute value in default configuration file. BFFA003C Memory pointer specified is not known. BFFA003D Unable to find any channel strings. BFFA003E Duplicate channel string. BFFA003F Duplicate virtual channel name. BFFA0040 Missing virtual channel name. BFFA0041 Bad virtual channel name. BFFA0042 Unassigned virtual channel name. BFFA0043 Bad virtual channel assignment. BFFA0044 Channel name required. BFFA0045 Channel name not allowed. BFFA0046 Attribute not valid for channel. BFFA0047 Attribute must be channel based. BFFA0048 Channel already excluded. BFFA0049 Missing option name (nothing before the '='). BFFA004A Missing option value (nothing after the '='). BFFA004B Bad option name. BFFA004C Bad option value. BFFA004D Operation only valid on a class driver session. BFFA004E "ivi.ini" filename is reserved. BFFA004F Duplicate run-time configuration entry. BFFA0050 Index parameter is one-based. BFFA0051 Index parameter is too high. BFFA0052 Attribute is not cacheable. BFFA0053 You cannot export a ViAddr attribute to the end-user. BFFA0054 Bad channel string in channel string list. BFFA0055 Bad prefix name in default configuration file. pi40iv_error_message VISA Status Codes: Status Description WARNINGS: 3FFF0002 Event enabled for one or more specified mechanisms. 3FFF0003 Event disabled for one or more specified mechanisms. 3FFF0004 Successful, but queue already empty. 3FFF0005 Specified termination character was read. 3FFF0006 Number of bytes transferred equals input count. 3FFF0077 Configuration non-existant or could not be loaded. 3FFF007D Open successful, but the device not responding. 3FFF0080 Wait successful, but more event objects available. 116 / 208

121 3FFF0082 Specified object reference is uninitialized. 3FFF0084 Attribute value not supported. 3FFF0085 Status code could not be interpreted. 3FFF0088 Specified I/O buffer type not supported. 3FFF0098 Successful, but invoke no handlers for this event. 3FFF0099 Successful but session has nested shared locks. 3FFF009A Successful but session has nested exclusive locks. 3FFF009B Successful but operation not asynchronous. ERRORS: BFFF0000 Unknown system error (miscellaneous error). BFFF000E Session or object reference is invalid. BFFF000F Resource is locked. BFFF0010 Invalid expression specified for search. BFFF0011 Resource is not present in the system. BFFF0012 Invalid resource reference specified. Parsing error. BFFF0013 Invalid access mode. BFFF0015 Timeout expired before operation completed. BFFF0016 Unable to deallocate session data structures. BFFF001B Specified degree is invalid. BFFF001C Specified job identifier is invalid. BFFF001D Attribute is not supported by the referenced object. BFFF001E Attribute state not supported by the referenced object. BFFF001F Specified attribute is read-only. BFFF0020 Lock type lock not supported by this resource. BFFF0021 Invalid access key. BFFF0026 Specified event type not supported by the resource. BFFF0027 Invalid mechanism specified. BFFF0028 A handler was not installed. BFFF0029 Handler reference either invalid or was not installed. BFFF002A Specified event context invalid. BFFF002D Event queue for specified type has overflowed. BFFF002F Event type must be enabled in order to receive. BFFF0030 User abort during transfer. BFFF0034 Violation of raw write protocol during transfer. BFFF0035 Violation of raw read protocol during transfer. BFFF0036 Device reported output protocol error during transfer. BFFF0037 Device reported input protocol error during transfer. BFFF0038 Bus error during transfer. BFFF0039 Unable to queue asynchronous operation. BFFF003A Unable to start operation because setup is invalid. BFFF003B Unable to queue the asynchronous operation. BFFF003C Insufficient resources to perform memory allocation. BFFF003D Invalid buffer mask specified. BFFF003E I/O error. BFFF003F Format specifier invalid. BFFF0041 Format specifier not supported. BFFF0042 Trigger line is currently in use. BFFF004A Service request not received for the session. BFFF004E Invalid address space specified. BFFF0051 Invalid offset specified. BFFF0052 Invalid access width specified. BFFF0054 Offset not accessible from this hardware. BFFF0055 Source and destination widths are different. BFFF0057 Session not currently mapped. BFFF0059 Previous response still pending. pi40iv_error_message 117 / 208

122 BFFF005F No listeners condition detected. BFFF0060 Interface not currently the controller in charge. BFFF0061 Interface not the system controller. BFFF0067 Session does not support this operation. BFFF006A A parity error occurred during transfer. BFFF006B A framing error occurred during transfer. BFFF006C An overrun error occurred during transfer. BFFF0070 Offset not properly aligned for operation access width. BFFF0071 Specified user buffer not valid. BFFF0072 Resource valid, but VISA cannot access it. BFFF0076 Width not supported by this hardware. BFFF0078 Invalid parameter value, parameter unknown. BFFF0079 Invalid protocol. BFFF007B Invalid window size. BFFF0080 Session currently contains a mapped window. BFFF0081 Operation not implemented. BFFF0083 Invalid length. BFFF0091 Invalid mode. BFFF009C Session did not have a lock on the resource. BFFF009D The device does not export any memory. BFFF009E VISA-required code library not located or not loaded. pi40iv_error_message VXIPnP Driver Status Codes: Status Description WARNINGS: 3FFC0101 Instrument does not have ID Query capability. 3FFC0102 Instrument does not have Reset capability. 3FFC0103 Instrument does not have Self-Test capability. 3FFC0104 Instrument does not have Error Query capability. 3FFC0105 Instrument does not have Revision Query capability. ERRORS: BFFC0001 Parameter 1 out of range, or error trying to set it. BFFC0002 Parameter 2 out of range, or error trying to set it. BFFC0003 Parameter 3 out of range, or error trying to set it. BFFC0004 Parameter 4 out of range, or error trying to set it. BFFC0005 Parameter 5 out of range, or error trying to set it. BFFC0006 Parameter 6 out of range, or error trying to set it. BFFC0007 Parameter 7 out of range, or error trying to set it. BFFC0008 Parameter 8 out of range, or error trying to set it. BFFC0011 Instrument failed the ID Query. BFFC0012 Invalid response from instrument. errormessage Variable Type ViChar[] Returns the user-readable message string that corresponds to the status code you specify. You must pass a ViChar array with at least 256 bytes. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the 118 / 208

123 pi40iv_clearerror function. Information about driver error codes. pi40iv_error_message 119 / 208

124 pi40iv_error_query pi40iv_error_query ViStatus pi40iv_error_query (ViSession instrumenthandle, ViPInt32 errorcode, ViChar _VI_FAR errormessage[]); Purpose This function reads an error code and a message from the instrument's error queue. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None errorcode Variable Type ViInt32 (passed by reference) Returns the error code read from the instrument's error queue. errormessage Variable Type ViChar[] Returns the error message string read from the instrument's error message queue. You must pass a ViChar array with at least 256 bytes. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 120 / 208

125 pi40iv_invalidateallattributes pi40iv_invalidateallattributes ViStatus pi40iv_invalidateallattributes(visession instrumenthandle) Purpose This function invalidates the cached values of all attributes for the session. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 121 / 208

126 pi40iv_revision_query pi40iv_revision_query ViStatus pi40iv_revision_query (ViSession instrumenthandle, ViChar _VI_FAR instrumentdriverrevision[], ViChar _VI_FAR firmwarerevision[]); Purpose This function returns the revision numbers of the instrument driver and instrument firmware. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None instrumentdriverrevision Variable Type ViChar[] Returns the instrument driver software revision numbers in the form of a string. You must pass a ViChar array with at least 256 bytes. firmwarerevision Variable Type ViChar[] Returns the instrument firmware revision numbers in the form of a string. You must pass a ViChar array with at least 256 bytes. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 122 / 208

127 pi40iv_reset pi40iv_reset ViStatus pi40iv_reset (ViSession instrumenthandle); Purpose This function resets the instrument to a known state and sends initialization commands to the instrument. The initialization commands set instrument settings such as Headers Off, Short Command form, and Data Transfer Binary to the state necessary for the operation of the instrument driver. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 123 / 208

128 pi40iv_resetwithdefaults pi40iv_resetwithdefaults ViStatus pi40iv_resetwithdefaults(visession instrumenthandle) Purpose This function resets the instrument and applies initial user specified settings from the Logical Name which was used to initialize the session. If the session was created without a Logical Name, this function is equivalent to the pi40iv_reset function. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 124 / 208

129 pi40iv_self_test pi40iv_self_test ViStatus pi40iv_self_test (ViSession instrumenthandle, ViPInt16 selftestresult, ViChar _VI_FAR selftestmessage[]); Purpose This function runs the instrument's self test routine and returns the test result(s). Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None selftestresult Variable Type ViInt16 (passed by reference) This control contains the value returned from the instrument self test. Zero means success. For any other code, see the device's operator's manual. Self-Test Code Description Passed self test 1 Self test failed selftestmessage Variable Type ViChar[] Returns the self-test response string from the instrument. See the device's operation manual for an explanation of the string's contents. You must pass a ViChar array with at least 256 bytes. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 125 / 208

130 pi40iv_disable pi40iv_disable (*not supported) ViStatus pi40iv_disable(visession instrumenthandle) Purpose This function places the instrument in a quiescent state where it has minimal or no impact on the system to which it is connected. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. * This function is a requirement of the IVI standard and is not supported in the Pickering pi40iv driver package. 126 / 208

131 pi40iv_getchannelname pi40iv_getchannelname ViStatus pi40iv_getchannelname (ViSession instrumenthandle, ViInt32 index, ViInt32 buffersize, ViChar channelname[]); Purpose This function returns the highest-level channel name that corresponds to the specific driver channel string that is in the channel table at an index you specify. By passing 0 for the buffer size, the caller can ascertain the buffer size required to get the entire channel name string and then call the function again with a sufficiently large buffer. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None index Variable Type ViInt32 A 1-based index into the channel table. buffersize Variable Type ViInt32 Pass the number of bytes in the ViChar array you specify for the Channel Name parameter. If the channel name, including the terminating NULL byte, contains more bytes than you indicate in this parameter, the function copies BufferSize - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. If you pass a negative number, the function copies the value to the buffer regardless of the number of bytes in the value. If you pass 0, you can pass VI_NULL for the Channel Name buffer parameter. Default Value: None channelname Variable Type ViChar[] Returns channel name that corresponds to the specific driver channel string that is in the channel table at an index you specify. The buffer must contain at least as many elements as the value you specify with the Buffer Size parameter. If the channel name description, including the terminating NUL byte, contains more bytes than you indicate with the Buffer Size parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns / 208

132 pi40iv_getchannelname If you pass 0 for the Buffer Size, you can pass VI_NULL for this parameter. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 128 / 208

133 pi40iv_close pi40iv_close ViStatus pi40iv_close (ViSession instrumenthandle); Purpose This function performs the following operations: - Closes the instrument I/O session. - Destroys the instrument driver session and all of its attributes. - Deallocates any memory resources the driver uses. Notes: (1) You must unlock the session before calling pi40iv_close. (2) After calling pi40iv_close, you cannot use the instrument driver again until you call pi40iv_init or pi40iv_initwithoptions. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 129 / 208

134 pi40iv_init pi40iv_init (*not supported) ViStatus pi40iv_init (ViRsrc resourcename, ViBoolean IDQuery, ViBoolean resetdevice, ViPSession instrumenthandle); Note: This driver doesn't support the pi40iv_init function, the pi40iv_initwithoptions need to be used, supplied with a correct option string. Purpose This function performs the following initialization actions: - Creates a new IVI instrument driver session. - Opens a session to the specified device using the interface and address you specify for the Resource Name parameter. - If the ID Query parameter is set to VI_TRUE, this function queries the instrument ID and checks that it is valid for this instrument driver. - If the Reset parameter is set to VI_TRUE, this function resets the instrument to a known state. - Sends initialization commands to set the instrument to the state necessary for the operation of the instrument driver. - Returns a ViSession handle that you use to identify the instrument in all subsequent instrument driver function calls. Note: This function creates a new session each time you invoke it. Although you can open more than one IVI session for the same resource, it is best not to do so. You can use the same session in multiple program threads. You can use the pi40iv_locksession and pi40iv_unlocksession functions to protect sections of code that require exclusive access to the resource. Parameter List resourcename Variable Type ViRsrc Pass the resource name of the device to initialize. You can also pass the name of a virtual instrument or logical name that you configure with the IVI Configuration utility. The virtual instrument identifies a specific device and specifies the initial settings for the session. A logical Name identifies a particular virtual instrument. Refer to the following table below for the exact grammar to use for this parameter. Optional fields are shown in square brackets ([]). Syntax PXI[bus]::<device>::INSTR TCPIP[board]::<IP address>::<bus>.<device>::instr GPIB[board]::<primary address>[::secondary address]::instr VXI[board]::<logical address>::instr GPIB-VXI[board]::<logical address>::instr ASRL<port>::INSTR <LogicalName> [VInstr->]<VirtualInstrument> If you do not specify a value for an optional field, the following values are used: 130 / 208

135 Optional Field Default Value bus 0 board 0 secondary address 31 pi40iv_init Examples The following table contains example valid values for this parameter. "Valid Value" - Description "TCPIP:: ::1.5::INSTR" - Board at logical bus 1, logical device 5 in the LXI chassis on LAN IP address "TCPIP:: ::2.3::INSTR" - Board at logical bus 2, logical device 3 in the LXI chassis on LAN IP address "PXI::4::INSTR" - PXI board at logical bus 0, logical device 4 "PXI2::15::INSTR" - PXI board at logical bus 2, logical device 15 "GPIB::22::INSTR" - GPIB board 0, primary address 22 no secondary address "GPIB::22::5::INSTR" - GPIB board 0, primary address 22 secondary address 5 "GPIB1::22::5::INSTR" - GPIB board 1, primary address 22 secondary address 5 "VXI::64::INSTR" - VXI board 0, logical address 64 "VXI1::64::INSTR" - VXI board 1, logical address 64 "GPIB-VXI::64::INSTR" - GPIB-VXI board 0, logical address 64 "GPIB-VXI1::64::INSTR" - GPIB-VXI board 1, logical address 64 "ASRL2::INSTR" - COM port 2 "SampleInstr" - Logical name "SampleInstr" "VInstr->xyz432" - Virtual Instrument "xyz432" "xyz432" - Logical Name or Virtual Instrument "xyz432" Note: You specify the resource name with the "VInstr->" if you have the logical name that is the same as the virtual instrument name and you want to explicitly use the virtual instrument name. Otherwise, the driver uses the logical name. IDQuery Variable Type ViBoolean Specify whether you want the instrument driver to perform an ID Query. Valid Range: VI_TRUE (1) - Perform ID Query (Default Value) VI_FALSE (0) - Skip ID Query When you set this parameter to VI_TRUE, the driver verifies that the instrument you initialize is a type that this driver supports. Circumstances can arise where it is undesirable to send an ID Query command string to the instrument. When you set this parameter to VI_FALSE, the function initializes the instrument without performing an ID Query. resetdevice Variable Type ViBoolean Specify whether you want the to reset the instrument during the initialization procedure. Valid Range: VI_TRUE (1) - Reset Device (Default Value) VI_FALSE (0) - Don't Reset instrumenthandle Variable Type ViSession (passed by reference) Returns a ViSession handle that you use to identify the instrument in all subsequent 131 / 208

136 pi40iv_init instrument driver function calls. Notes: (1) This function creates a new session each time you invoke it. This is useful if you have multiple physical instances of the same type of instrument. (2) Avoid creating multiple concurrent sessions to the same physical instrument. Although you can create more than one IVI session for the same resource, it is best not to do so. A better approach is to use the same IVI session in multiple execution threads. You can use functions pi40iv_locksession and pi40iv_unlocksession to protect sections of code that require exclusive access to the resource. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. * This function is a requirement of the IVI standard and is not supported in the Pickering pi40iv driver package. 132 / 208

137 pi40iv_initwithoptions pi40iv_initwithoptions ViStatus pi40iv_initwithoptions (ViRsrc resourcename, ViBoolean IDQuery, ViBoolean resetdevice, ViConstString optionstring, ViPSession instrumenthandle); Purpose This function performs the following initialization actions: - Creates a new IVI instrument driver and optionally sets the initial state of the following session attributes: PI40IV_ATTR_RANGE_CHECK PI40IV_ATTR_QUERY_INSTR_STATUS PI40IV_ATTR_CACHE PI40IV_ATTR_SIMULATE PI40IV_ATTR_RECORD_COERCIONS PI40IV_ATTR_DRIVER_SETUP Note: The PI40IV_ATTR_DRIVER_SETUP attribute must be set. This attribute string contains the card type number and without it the driver doesn't know what card to operate. See section "optionstring" under "Parameter List" how to use these attributes. Because the pi40iv_init can't be supplied with a option string (that contains the card type number) this function isn't supported and returns an error. - Opens a session to the specified device using the interface and address you specify for the Resource Name parameter. - If the ID Query parameter is set to VI_TRUE, this function queries the instrument ID and checks that it is valid for this instrument driver. - If the Reset parameter is set to VI_TRUE, this function resets the instrument to a known state. - Sends initialization commands to set the instrument to the state necessary for the operation of the instrument driver. - Returns a ViSession handle that you use to identify the instrument in all subsequent instrument driver function calls. Note: This function creates a new session each time you invoke it. Although you can open more than one IVI session for the same resource, it is best not to do so. You can use the same session in multiple program threads. You can use the pi40iv_locksession and pi40iv_unlocksession functions to protect sections of code that require exclusive access to the resource. Parameter List resourcename Variable Type ViRsrc Pass the resource name of the device to initialize. You can also pass the name of a virtual instrument or logical name that you configure with the IVI Configuration utility. The virtual instrument identifies a specific device and specifies the initial settings for the session. A logical Name identifies a particular virtual instrument. Refer to the following table below for the exact grammar to use for this parameter. Optional fields are shown in square brackets ([]). Syntax 133 / 208

138 PXI[bus]::<device>::INSTR TCPIP[board]::<IP address>::<bus>.<device>::instr GPIB[board]::<primary address>[::secondary address]::instr VXI[board]::<logical address>::instr GPIB-VXI[board]::<logical address>::instr ASRL<port>::INSTR <LogicalName> [VInstr->]<VirtualInstrument> If you do not specify a value for an optional field, the following values are used: Optional Field Default Value bus 0 board 0 secondary address 31 Examples The following table contains example valid values for this parameter. "Valid Value" - Description "TCPIP:: ::1.5::INSTR" - Board at logical bus 1, logical device 5 in the LXI chassis on LAN IP address "TCPIP:: ::2.3::INSTR" - Board at logical bus 2, logical device 3 in the LXI chassis on LAN IP address "PXI::4::INSTR" - PXI board at logical bus 0, logical device 4 "PXI2::15::INSTR" - PXI board at logical bus 2, logical device 15 "GPIB::22::INSTR" - GPIB board 0, primary address 22 no secondary address "GPIB::22::5::INSTR" - GPIB board 0, primary address 22 secondary address 5 "GPIB1::22::5::INSTR" - GPIB board 1, primary address 22 secondary address 5 "VXI::64::INSTR" - VXI board 0, logical address 64 "VXI1::64::INSTR" - VXI board 1, logical address 64 "GPIB-VXI::64::INSTR" - GPIB-VXI board 0, logical address 64 "GPIB-VXI1::64::INSTR" - GPIB-VXI board 1, logical address 64 "ASRL2::INSTR" - COM port 2 "SampleInstr" - Logical name "SampleInstr" "VInstr->xyz432" - Virtual Instrument "xyz432" "xyz432" - Logical Name or Virtual Instrument "xyz432" Note: You specify the resource name with the "VInstr->" if you have the logical name that is the same as the virtual instrument name and you want to explicitly use the virtual instrument name. Otherwise, the driver uses the logical name. IDQuery Variable Type ViBoolean Specify whether you want the instrument driver to perform an ID Query. Valid Range: VI_TRUE (1) - Perform ID Query (Default Value) VI_FALSE (0) - Skip ID Query When you set this parameter to VI_TRUE, the driver verifies that the instrument you initialize is a type that this driver supports. Circumstances can arise where it is undesirable to send an ID Query command string to the instrument. When you set this parameter to VI_FALSE, the function initializes the instrument without performing an ID Query. resetdevice pi40iv_initwithoptions 134 / 208

139 Variable Type ViBoolean Specify whether you want the to reset the instrument during the initialization procedure. Valid Range: VI_TRUE (1) - Reset Device (Default Value) VI_FALSE (0) - Don't Reset optionstring Variable Type ViConstString You can use this control to set the initial value of certain attributes for the session. The following table lists the attributes and the name you use in this parameter to identify the attribute. Name Attribute Defined Constant RangeCheck PI40IV_ATTR_RANGE_CHECK QueryInstrStatus PI40IV_ATTR_QUERY_INSTR_STATUS Cache PI40IV_ATTR_CACHE Simulate PI40IV_ATTR_SIMULATE RecordCoercions PI40IV_ATTR_RECORD_COERCIONS DriverSetup PI40IV_ATTR_DRIVER_SETUP pi40iv_initwithoptions The format of this string is, "AttributeName=Value" where AttributeName is the name of the attribute and Value is the value to which the attribute will be set. To set multiple attributes, separate their assignments with a comma. If you pass NULL or an empty string for this parameter and a VISA resource descriptor for the Resource Name parameter, the session uses the default values for the attributes. The default values for the attributes are shown below: Attribute Name Default Value RangeCheck VI_TRUE QueryInstrStatus VI_TRUE Cache VI_TRUE Simulate VI_FALSE RecordCoercions VI_FALSE DriverSetup Model:40-XXX-XXX; Note: See below for more info If you pass NULL or an empty string for this parameter and a virtual instrument or logical name for the Resource Name parameter, the session uses the values that you configure for virtual instrument or logical name with the IVI Configuration utility. You can override the values of the attributes by assigning a value explicitly in a string you pass for this parameter. You do not have to specify all of the attributes and may leave any of them out. If you do not specify one of the attributes, its default value or the value that you configure with the IVI Configuration utility will be used. The following are the valid values for ViBoolean attributes: True: 1, TRUE, or VI_TRUE False: 0, False, or VI_FALSE Default Value: "Simulate=0,RangeCheck=1,QueryInstrStatus=1,Cache=1,DriverSetup=Model:40- XXX-XXX;" Some examples of how the DriverSetup attribute (PI40IV_ATTR_DRIVER_SETUP) of the option string could look like: 135 / 208

140 pi40iv_initwithoptions Model: ; Model: S; Model: x8; Model: x8; Model: S- 180x16; Model: /2; Model: /4; Model: S- 32/1; Model: S- D/16/1; 92 x 4 Matrix module 55 x 8 Screened matrix module 276 x 8 BRIC matrix system BRIC-4 in 92x8 configuration BRIC-8 in 180x16 screened configuration 99 channel 2 pole high density multiplexer 49 channel 4 pole high density multiplexer 32 channel 1 pole screened multiplexer 16 channel 1 pole dual screened multiplexer Note: both "Model:" at the beginning and ";" at the end must be added for the driver to recognize the correct card type. The card model number must be added with all extra numbers and letters just like in the pickering brochures. For example if there is a screened module add "-S" after card number. If you have a BRIC system add "-NNNxNN" for the matrix size. Special modules like the need to have the channel and pole number added after the card model number. If you have a S card see Configurable Product In addition there are two "Driver Setup" options which are specific to Pickering devices and do not conform to the IVI specification as follows: DisMuxCheck; To disable connection checking and allow full operation of MUX(M) devices. NoClosureLimit; To disable relay closure limit checking and settle delay. instrumenthandle Variable Type ViSession (passed by reference) Returns a ViSession handle that you use to identify the instrument in all subsequent instrument driver function calls. Notes: (1) This function creates a new session each time you invoke it. This is useful if you have multiple physical instances of the same type of instrument. (2) Avoid creating multiple concurrent sessions to the same physical instrument. Although you can create more than one IVI session for the same resource, it is best not to do so. A better approach is to use the same IVI session in multiple execution threads. You can use functions pi40iv_locksession and pi40iv_unlocksession to protect sections of code that require exclusive access to the resource. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information 136 / 208

141 from the driver, call the pi40iv_clearerror function. Information about driver error codes. pi40iv_initwithoptions 137 / 208

142 Pickering Custom Specific Driver Functions Pickering Custom Specific Driver Functions Each of these are essentially a wrapper to a Pickering direct driver function. As such they are not IVI class compliant. The set functions should not be used in conjunction with IVI Class compliant functions. pi40iv_getnumberinputsubs pi40iv_getinputsizebits pi40iv_getinputsizedwords pi40iv_getinputbit pi40iv_getinputsub pi40iv_getnumberoutputsubs pi40iv_getoutputsizebits pi40iv_getoutputsizedwords pi40iv_setoutputbit pi40iv_setoutputsub pi40iv_getoutputbit pi40iv_getoutputsub pi40iv_subinfo 138 / 208

143 Data Formats Data Formats Two basic data formats are used by the driver. Bit Number The individual output to be affected by functions such as pi40iv_setoutputbit is specified by a bit number value. For any sub-unit type other than a matrix, this unity-based number directly specifies the affected output channel. For a matrix sub-unit, the bit number of a crosspoint is determined by folding on the rowaxis. For example, in a matrix of dimensions 8 rows x 12 columns, bit number 13 represents the crosspoint (row 2, column 1): Data Array Functions affecting all of a sub-unit's outputs such as pi40iv_setoutputsub utilise a onedimensional data array (or vector) of 32-bit longwords. In the array, each bit represents the state of one output channel: '0' for OFF, '1' for ON. The least significant bit of the base element of the array corresponds to channel 1. More significant bits correspond to higher-numbered channels. For a matrix sub-unit, bit assignments follow the same pattern as that used to determine bit numbers. Hence for the matrix example above: Element 0 bit 0 = row 1 column 1 Element 0 bit 11 = row 1 column 12 Element 0 bit 12 = row 2 column 1 Element 2 bit 31 = row 8 column 12 Identical formatting is employed for the results of the pi40iv_getinputsub and pi40iv_getoutputsub functions. 139 / 208

144 pi40iv_getnumberinputsubs pi40iv_getnumberinputsubs (direct driver equivalent PIL_EnumerateSubs/PIPLX_EnumerateSubs) ViStatus pi40iv_getnumberinputsubs(visession instrumenthandle, ViUInt32 *InSubs); Purpose Obtains the numbers of input sub-units implemented on the specified card. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None InSubs Variable Type ViUInt32 (passed by reference) Pointer to a variable to receive the number of INPUT sub-units. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 140 / 208

145 pi40iv_getinputsizebits pi40iv_getinputsizebits (direct driver equivalent PIL_SubInfo/PIPLX_SubInfo) ViStatus pi40iv_getinputsizebits(visession instrumenthandle, ViUInt32 InSub, ViUInt32 *Size); Purpose Obtains the total number of inputs on a sub-unit as a bit count. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None InSub Variable Type ViUInt32 The number of the input sub unit to be accessed. These start from 1, use the "pi40iv_getnumberinputsubs" function to find how many input sub units are on the card. Size Variable Type ViUInt32 (passed by reference) Pointer to a variable to receive the total number of inputs on the sub-unit as a bit count i.e. the number of bits required to hold the input data. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 141 / 208

146 pi40iv_getinputsizedwords pi40iv_getinputsizedwords (direct driver equivalent PIL_SubInfo/PIPLX_SubInfo) ViStatus pi40iv_getinputsizedwords(visession instrumenthandle, ViUInt32 InSub, ViUInt32 *Size); Purpose Obtains the total number of inputs on a sub-unit as a double word count. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None InSub Variable Type ViUInt32 The number of the input sub unit to be accessed. These start from 1, use the "pi40iv_getnumberinputsubs" function to find how many input sub units are on the card. Size Variable Type ViUInt32 (passed by reference) Pointer to a variable to receive the total number of inputs on the sub-unit as a double word count i.e. the number of double words required to hold the input data. Note Most digital cards have a maximum of 32 inputs so the Size value returned will normally be 1. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 142 / 208

147 pi40iv_getinputbit pi40iv_getinputbit (also pi40iv_readbit - deprecated) (direct driver equivalent PIL_ReadBit/PIPLX_ReadBit) ViStatus pi40iv_getinputbit(visession instrumenthandle, ViUInt32 InSub, ViUInt32 BitNum, ViUInt32 *State); Purpose Obtains the state of an individual input.. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None InSub Variable Type ViUInt32 The number of the input sub unit to be accessed. These start from 1, use the "pi40iv_getnumberinputsubs" function to find how many input sub units are on the card. BitNum Variable Type ViUInt32 The number / position of the input to be read. These start from 1, use the "pi40iv_getinputsizebits" function to find how many input bit positions are on this sub unit. State Variable Type ViUInt32 (passed by reference) Pointer to a double word variable to receive the state (0 or 1) of the specified input. Note For a Matrix sub-unit, the result is folded into the vector on its row-axis: see Data Formats. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 143 / 208

148 pi40iv_getinputsub pi40iv_getinputsub (also pi40iv_readsub - deprecated) (direct driver equivalent PIL_ReadSub/PIPLX_ReadSub) ViStatus pi40iv_getinputsub(visession instrumenthandle, ViUInt32 InSub, ViUInt32 *Data); Purpose Obtains the current state of all inputs of a sub-unit. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None InSub Variable Type ViUInt32 The number of the input sub unit to be accessed. These start from 1, use the "pi40iv_getnumberinputsubs" function to find how many input sub units are on the card. Data Variable Type ViUInt32 (passed by reference) Pointer to a double word array (ViUInt32[]) variable to receive all the inputs on a sub unit. The array must be large enough to receive the data i.e. use the function call "pi40iv_getinputsizedwords" to obtain the number of array elements required. Each element in the array will show the state of 32 inputs, e.g. if the sub unit has 16 inputs an array of 1 element is required and this element (Data[0]) will contain the last 16 bits (ignore the top 16 bits). Most digital cards have a maximum of 32 inputs so a pointer to a single variable of type ViUInt32 (e.g. &Data) can be used to receive the data. Note For a Matrix sub-unit, the result is folded into the vector on its row-axis: see Data Formats. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 144 / 208

149 pi40iv_getnumberoutputsubs pi40iv_getnumberoutputsubs (direct driver equivalent PIL_EnumerateSubs/PIPLX_EnumerateSubs) ViStatus pi40iv_getnumberoutputsubs(visession instrumenthandle, ViUInt32 *OutSubs); Purpose Obtains the numbers of output sub-units implemented on the specified card. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None OutSubs Variable Type ViUInt32 (passed by reference) Pointer to a variable to receive the number of OUTPUT sub-units. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 145 / 208

150 pi40iv_getoutputsizebits pi40iv_getoutputsizebits (direct driver equivalent PIL_SubInfo/PIPLX_SubInfo) ViStatus pi40iv_getoutputsizebits(visession instrumenthandle, ViUInt32 OutSub, ViUInt32 *Size); Purpose Obtains the total number of outputs on a sub-unit as a bit count. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None OutSub Variable Type ViUInt32 The number of the Output sub unit to be accessed. These start from 1, use the "pi40iv_getnumberoutputsubs" function to find how many output sub units are on the card. Size Variable Type ViUInt32 (passed by reference) Pointer to a variable to receive the total number of outputs on the sub-unit as a bit count i.e. the number of bits required to hold the output data. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 146 / 208

151 pi40iv_getoutputsizedwords pi40iv_getoutputsizedwords (direct driver equivalent PIL_SubInfo/PIPLX_SubInfo) ViStatus pi40iv_getoutputsizedwords(visession instrumenthandle, ViUInt32 OutSub, ViUInt32 *Size); Purpose Obtains the total number of outputs on a sub-unit as a double word count. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None OutSub Variable Type ViUInt32 The number of the Output sub unit to be accessed. These start from 1, use the "pi40iv_getnumberoutputsubs" function to find how many output sub units are on the card. Size Variable Type ViUInt32 (passed by reference) Pointer to a variable to receive the total number of outputs on the sub-unit as a double word count i.e. the number of double words required to hold the output data. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 147 / 208

152 pi40iv_setoutputbit pi40iv_setoutputbit (direct driver equivalent PIL_OpBit/PIPLX_OpBit) ViStatus pi40iv_setoutputbit(visession instrumenthandle, ViUInt32 OutSub, ViUInt32 BitNum, ViUInt32 State); Purpose Sets the state of an individual output.. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None OutSub Variable Type ViUInt32 The number of the output sub unit to be accessed. These start from 1, use the "pi40iv_getnumberoutputsubs" function to find how many output sub units are on the card. BitNum Variable Type ViUInt32 The number / position of the output to be set. These start from 1, use the "pi40iv_getoutputsizebits" function to find how many output bit positions are on this sub unit. State Variable Type ViUInt32 A double word variable to set the state (1 to energise, 0 to de-energise) of the specified output. Note For a Matrix sub-unit, the data is folded into the vector on its row-axis: see Data Formats. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 148 / 208

153 pi40iv_setoutputsub pi40iv_setoutputsub (direct driver equivalent PIL_WriteSub/PIPLX_WriteSub) ViStatus pi40iv_setoutputsub(visession instrumenthandle, ViUInt32 OutSub, ViUInt32 *Data); Purpose Sets all outputs of a sub-unit to the supplied bit-pattern. The number of least significant bits corresponding to the size of the sub-unit are written. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None OutSub Variable Type ViUInt32 The number of the output sub unit to be accessed. These start from 1, use the "pi40iv_getnumberoutputsubs" function to find how many Output sub units are on the card. Data Variable Type ViUInt32 (passed by reference) Pointer to a double word array (ViUInt32[]) variable containing the bit pattern to be written to all the outputs on a sub unit. The array must be large enough to represent all the outputs on the specified sub unit i.e. use the function call "pi40iv_getinputsizedwords" to obtain the number of array elements required. Each element in the array contains data for 32 outputs, e.g. if the sub unit has 67 outputs an array of 3 elements is required and the third element (Data[2]) contains the last 3 bits (ignore the top 29 bits). If the data array does not contain sufficient bits to represent the bit pattern for the specified sub unit undefined data will be written to the more significant bits. Note For a Matrix sub-unit, the data is folded into the vector on its row-axis: see Data Formats. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 149 / 208

154 pi40iv_getoutputbit pi40iv_getoutputbit (direct driver equivalent PIL_ViewBit/PIPLX_ViewBit) ViStatus pi40iv_getoutputbit(visession instrumenthandle, ViUInt32 OutSub, ViUInt32 BitNum, ViUInt32 *State); Purpose Obtains the state of an individual output. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None OutSub Variable Type ViUInt32 The number of the output sub unit to be accessed. These start from 1, use the "pi40iv_getnumberoutputsubs" function to find how many output sub units are on the card. BitNum Variable Type ViUInt32 The number / position of the output to be read. These start from 1, use the "pi40iv_getoutputsizebits" function to find how many output bit positions are on this sub unit. State Variable Type ViUInt32 (passed by reference) Pointer to a double word variable to receive the state (0 or 1) of the specified output. Note For a Matrix sub-unit, the result is folded into the vector on its row-axis: see Data Formats. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 150 / 208

155 pi40iv_getoutputsub pi40iv_getoutputsub (direct driver equivalent PIL_ViewSub/PIPLX_ViewSub) ViStatus pi40iv_getoutputsub(visession instrumenthandle, ViUInt32 OutSub, ViUInt32 *Data); Purpose Obtains the state of all outputs of a sub-unit. The result fills the number of least significant bits corresponding to the size of the sub-unit. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None OutSub Variable Type ViUInt32 The number of the output sub unit to be accessed. These start from 1, use the "pi40iv_getnumberoutputsubs" function to find how many output sub units are on the card. Data Variable Type ViUInt32 (passed by reference) Pointer to a double word array (ViUInt32[]) variable to receive all the outputs on a sub unit. The array must be large enough to receive the data i.e. use the function call "pi40iv_getoutputsizedwords" to obtain the number of array elements required. Each element in the array will show the state of 32 outputs, e.g. if the sub unit has 67 outputs an array of 3 elements is required and the third element (Data[2]) will contain the last 3 bits (ignore the top 29 bits). Note For a Matrix sub-unit, the result is folded into the vector on its row-axis: see Data Formats. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 151 / 208

156 pi40iv_subinfo pi40iv_subinfo (direct driver equivalent PIL_SubInfo/PIPLX_SubInfo) ViStatus pi40iv_subinfo(visession instrumenthandle, ViUInt32 Sub, ViInt16 InOut, ViUInt32 *Type, ViUInt32 *Rows, ViUInt32 *Cols); Purpose Obtains the numbers of input and output sub-units implemented on the specified card. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None Sub Variable Type ViUInt32 The number of the input or output sub unit to be accessed. These start from 1, use the "pi40iv_getnumberinputsubs" or "pi40iv_getnumberoutputsubs" function to find how many sub units are on the card. InOut Variable Type ViInt16 Type of sub unit to be used: 0 for INPUT, 1 for OUTPUT Type Variable Type ViUInt32 Pointer to a variable to receive type code. Output sub-unit type codes are: 1 - TYPE_SW (uncommitted switch) 2 - TYPE_MUX (multiplexer single-channel) 3 - TYPE_MUXM (multiplexer, multi-channel) 4 - TYPE_MAT (matrix - LF) 5 - TYPE_MATR (matrix - RF) 6 - TYPE_DIG (digital outputs) 7 - TYPE_RES (programmable resistor) 8 - TYPE_ATTEN (programmable RF attenuator) 9 - TYPE_PSUDC (DC power supply) Corresponding enumerated constants are provided in PILPXI.H. Input sub-unit type codes are: 1 - INPUT Rows Variable Type ViUInt32 Pointer to variable to receive row count. Returns 1 for all types except matrix. Cols Variable Type ViUInt / 208

157 Pointer to variable to receive column count pi40iv_subinfo Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterror function. To clear the error information from the driver, call the pi40iv_clearerror function. Information about driver error codes. 153 / 208

158 PI40IV_ATTR_QUERY_INSTR_STATUS See: PI40IV_ATTR_QUERY_INSTRUMENT_STATUS This attribute is no longer supported, please use the "PI40IV_ATTR_QUERY_INSTRUMENT_STATUS" attribute. 154 / 208

159 PI40IV_ATTR_NUM_CHANNELS See: PI40IV_ATTR_CHANNEL_COUNT This attribute is no longer supported, please use the "PI40IV_ATTR_CHANNEL_COUNT" attribute. 155 / 208

160 PI40IV_ATTR_RESOURCE_DESCRIPTOR See: PI40IV_ATTR_IO_RESOURCE_DESCRIPTOR This attribute is no longer supported, please use the "PI40IV_ATTR_IO_RESOURCE_DESCRIPTOR" attribute. 156 / 208

161 pi40iv_clearerrorinfo pi40iv_clearerrorinfo ViStatus pi40iv_clearerrorinfo (ViSession instrumenthandle); Purpose This function clears the error information for the current execution thread and the IVI session you specify. If you pass VI_NULL for the Instrument Handle parameter, this function clears the error information only for the current execution thread. The error information includes a primary error code, secondary error code, and an error elaboration string. For a particular session, this information is the same as the values held in the following attributes: PI40IV_ATTR_PRIMARY_ERROR PI40IV_ATTR_SECONDARY_ERROR PI40IV_ATTR_ERROR_ELABORATION This function sets the primary and secondary error codes to VI_SUCCESS (0), and sets the error elaboration string to "". The IVI Library also maintains this error information separately for each thread. This is useful if you do not have a session handle to pass to pi40iv_clearerrorinfo or pi40iv_geterrorinfo, which occurs when a call to pi40iv_init or i40iv_initwithoptions fails. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: None Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterrorinfo function. To clear the error information from the driver, call the i40iv_clearerrorinfo function. Information about driver error codes. 157 / 208

162 pi40iv_geterrorinfo pi40iv_geterrorinfo ViStatus pi40iv_geterrorinfo (ViSession instrumenthandle, ViPStatus primaryerror, ViPStatus secondaryerror, ViChar _VI_FAR errorelaboration[]); Purpose This function returns the error information associated with an IVI session or with the current execution thread. If you specify a valid IVI session for the Instrument Handle parameter, this function retrieves and then clears the error information for the session. If you pass VI_NULL for the Instrument Handle parameter, this function retrieves and then clears the error information for the current execution thread. The error information includes a primary error, secondary error, and an error elaboration string. For a particular session, this information is the same as the values held in the following attributes: PI40IV_ATTR_PRIMARY_ERROR PI40IV_ATTR_SECONDARY_ERROR PI40IV_ATTR_ERROR_ELABORATION The IVI Library also maintains this error information separately for each thread. This is useful if you do not have a session handle to pass to pi40iv_geterrorinfo or pi40iv_clearerrorinfo, which occurs when a call to pi40iv_init or pi40iv_initwithoptions fails. You can call pi40iv_error_message to obtain a text description of the primary or secondary error value. Parameter List instrumenthandle Variable Type ViSession The ViSession handle that you obtain from the pi40iv_init or pi40iv_initwithoptions function. The handle identifies a particular instrument session. Default Value: VI_NULL primaryerror Variable Type ViStatus (passed by reference) The primary error code for the session or execution thread. The value is the same as the one held by the attribute PI40IV_ATTR_PRIMARY_ERROR. A value of VI_SUCCESS (0) indicates that no error occurred, A positive value indicates a warning. A negative value indicates an error. You can call pi40iv_error_message to get a text description of the value. If you are not interested in this value, you can pass VI_NULL. secondaryerror Variable Type ViStatus (passed by reference) The secondary error code for the session or execution thread. If the primary error code is non-zero, the secondary error code can further describe the error or warning condition. The value is the same as the one held by the attribute PI40IV_ATTR_SECONDARY_ERROR. A value of VI_SUCCESS (0) indicates no further description. You can call pi40iv_error_message to get a text description of the value. If you are not interested in this value, you can pass VI_NULL. errorelaboration Variable Type ViChar[] 158 / 208

163 pi40iv_geterrorinfo The error elaboration string for the session or execution thread. If the primary error code is non-zero, the elaboration string can further describe the error or warning condition. The value is the same as the one held by the attribute PI40IV_ATTR_ERROR_ELABORATION. If you are not interested in this value, you can pass VI_NULL. Otherwise, you must pass a ViChar array with at least 256 bytes. Return Value Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You examine the status code from each call to an instrument driver function to determine if an error occurred. To obtain a text description of the status code, call the pi40iv_error_message function. To obtain additional information about the error condition, call the pi40iv_geterrorinfo function. To clear the error information from the driver, call the pi40iv_clearerrorinfo function. Information about driver error codes. 159 / 208

164 PI40IV_ATTR_IS_SCANNING PI40IV_ATTR_IS_SCANNING Note: This attribute is not implemented/supported by Pickering Interfaces. Data Type: ViBoolean Restrictions: Not settable. Description: This attribute indicates whether the switch module has completed the scan operation. The value VI_TRUE indicates that the scan is complete. 160 / 208

165 PI40IV_ATTR_SCAN_ADVANCED_OUTPUT PI40IV_ATTR_SCAN_ADVANCED_OUTPUT Note: This attribute is not implemented/supported by Pickering Interfaces. Data Type: Restrictions: Description: ViInt32 This attribute specifies the method you want to use to notify another instrument that all signals going through the switch module have settled following the processing of one entry in the scan list. Values: PI40IV_VAL_NONE 0 The switch module does not produce a Scan Advanced Output trigger. PI40IV_VAL_EXTERNAL 2 External Trigger. The switch module produces the Scan Advanced Output trigger on the external trigger output. PI40IV_VAL_GPIB_SRQ 5 The switch module produces the GPIB Service Request in place of the Scan Advanced Output trigger. PI40IV_VAL_TTL0 111 The switch module produces the Scan Advanced Output on the VXIbus TTL0 or PXI TRIG0 line. PI40IV_VAL_TTL1 112 The switch module produces the Scan Advanced Output on the VXIbus TTL1 or PXI TRIG1 line. PI40IV_VAL_TTL2 113 The switch module produces the Scan Advanced Output on the VXIbus TTL2 or PXI TRIG2 line. PI40IV_VAL_TTL3 114 The switch module produces the Scan Advanced Output on the VXIbus TTL3 or PXI TRIG3 line. PI40IV_VAL_TTL4 115 The switch module produces the Scan Advanced Output on the VXIbus TTL4 or PXI TRIG4 line. PI40IV_VAL_TTL5 116 The switch module produces the Scan Advanced Output on the VXIbus TTL5 or PXI TRIG5 line. PI40IV_VAL_TTL6 117 The switch module produces the Scan Advanced Output on the VXIbus TTL6 or PXI TRIG6 line. PI40IV_VAL_TTL7 118 The switch module produces the Scan Advanced Output on the VXIbus TTL7 or PXI TRIG7 line. PI40IV_VAL_ECL0 119 The switch module produces the Scan Advanced Output on the VXIbus ECL0 line. PI40IV_VAL_ECL1 120 The switch module produces the Scan Advanced Output on the VXIbus ECL1 line. PI40IV_VAL_PXI_STAR 125 The switch module produces the Scan Advanced Output on the PXI STAR trigger bus. PI40IV_VAL_RTSI_0 140 The switch module produces the Scan Advanced Output on RTSI line 0. PI40IV_VAL_RTSI_ / 208

166 The switch module produces the Scan Advanced Output on RTSI line 1. PI40IV_VAL_RTSI_2 142 The switch module produces the Scan Advanced Output on RTSI line 2. PI40IV_VAL_RTSI_3 143 The switch module produces the Scan Advanced Output on RTSI line 3. PI40IV_VAL_RTSI_4 144 The switch module produces the Scan Advanced Output on RTSI line 4. PI40IV_VAL_RTSI_5 145 The switch module produces the Scan Advanced Output on RTSI line 5. PI40IV_VAL_RTSI_6 146 The switch module produces the Scan Advanced Output on RTSI line 6. PI40IV_ATTR_SCAN_ADVANCED_OUTPUT 162 / 208

167 PI40IV_ATTR_SCAN_DELAY PI40IV_ATTR_SCAN_DELAY Note: This attribute is not implemented/supported by Pickering Interfaces. Data Type: Restrictions: Description: ViReal64 This attribute specifies the minimum amount of time the switch module waits before it asserts the scan advanced output trigger after opening or closing the switch. The switch module always waits for debounce before asserting the trigger. Thus, the actual delay will always be the greater value of the settling time and the value you specify as the switch delay. The units are seconds. Due to different designs of the switch modules, the actual time might be longer. 163 / 208

168 PI40IV_ATTR_SCAN_LIST PI40IV_ATTR_SCAN_LIST Note: This attribute is not implemented/supported by Pickering Interfaces. Data Type: Restrictions: Description: ViString This attribute contains a scan list, which is a string that specifies channel connections and trigger conditions. The pi40iv_initiatescan function makes or breaks connections and waits for triggers according to the instructions in the scan list. The scan list is comprised of channel names that you separate with special characters. These special characters determine the operations the scanner performs on the channels when it executes this scan list. To create a path between two channels, use the following character between the two channel names: -> (a dash followed by a '>' sign) Example: "CH1->CH2" tells the switch to make a path from channel CH1 to channel CH2. To break or clear a path, use the following character as a prefix before the path: ~ (tilde) Example: "~CH1->CH2" tells the switch to break the path from channel CH1 to channel CH2. To tell the switch module to wait for a trigger event, use the following character as a separator between paths: ; (semicolon) Example: "CH1->CH2;CH3->CH4" tells the switch to make the path from channel CH1 to channel CH2, wait for a trigger, and then make the path from CH3 to CH4. To tell the switch module to create multiple paths simultaneously, use the following character as a separator between the paths:, (comma) Example: "A->B;CH1->CH2,CH3->CH4" instructs the scanner to make the path between channels A and B, wait for a trigger, and then simultaneously make the paths between channels CH1 and CH2 and between channels CH3 and CH / 208

169 PI40IV_ATTR_SCAN_MODE PI40IV_ATTR_SCAN_MODE Note: This attribute is not implemented/supported by Pickering Interfaces. Data Type: Restrictions: Description: ViInt32 This attribute specifies what happens to existing connections that conflict with the connections you make in a scan list. For example, if CH1 is already connected to CH2 and the scan list instructs the switch module to connect CH1 to CH3, this attribute specifies what happens to the connection between CH1 and CH2. If the value of this attribute is PI40IV_VAL_NONE, the switch module takes no action on existing paths. If the value is PI40IV_VAL_BREAK_BEFORE_MAKE, the switch module breaks conflicting paths before making new ones. If the value is PI40IV_VAL_BREAK_AFTER_MAKE, the switch module breaks conflicting paths after making new ones. Most switch modules support only one of the possible values. In such cases, this attribute serves as an indicator of the module's behavior. Values: PI40IV_VAL_NONE 0 No implicit action on connections when scanning PI40IV_VAL_BREAK_BEFORE_MAKE 1 When scanning, the switch module breaks existing connections before making new connections. PI40IV_VAL_BREAK_AFTER_MAKE 2 When scanning, the switch module breaks existing connections after making new connections. 165 / 208

170 Configurable Products Configurable Products S The S BRIC Microware Multiplexer is a configurable BRIC which can act as a singel to dual multiplexer with 1 to 2 in-channels (called T1 and T2) and 36 out-channels. This means that the BRIC can be a singel 36x1 mux or a dual mux with no more than 36 out channels. For example it can be configured as a dual 24x1/12x1 mux or a dual 18x1/18x1 mux. For the driver to understand how to configure the BRIC you need to add more information to the driver setup option string. This is done by adding an extra part called "Config" after the "Model" part. See table below for info: Some examples of how the DriverSetup attribute (PI40IV_ATTR_DRIVER_SETUP) of the option string could look like in a S BRIC: Model: S; Model: S;Config:36T1_0T2; Model: S;Config:24T1_12T2; Model: S;Config:18T1_18T2; Model: S;Config:20T1_16T2; Model: S;Config:34T1_2T2; Model: S;Config:30T1_6T2; Model: S;Config:XXT1_XXT2; Default for the S with no "Config" part added. 36x1 mux with common T1 36 channel mux with common channel T1 Dual mux. 24 channel with common T1 and 12 channel with common T2 Dual mux. 18 channel with common T1 and 18 channel with common T2 Dual mux. 20 channel with common T1 and 16 channel with common T2 Dual mux. 34 channel with common T1 and 2 channel with common T2 Dual mux. 30 channel with common T1 and 6 channel with common T2 Dual mux. XX channel with common T1 and XX channel with common T2 Note: both "Model:", "Config:" and the two ";" in the middle and at the end must be added for the driver to recognize the correct card type. 166 / 208

171 More driver info More driver info This section contains different information that is good to know for a user of this driver. Configuration channels The channel attribute PI40IV_ATTR_IS_CONFIGURATION_CHANNEL specifies if the channel is available for external connections or if the channel is internally used for path creation. If this attribute is set to VI_FALSE (which is default), then the channel is considered a standard channel and can be explicitly connected to another channel. If the value is set to VI_TRUE, then the channel is no longer accessible to the user and has been turned over to the driver for its use. The purpose of this attribute is to tell the driver what channels are available for path creation. For example, if the user specifies a column-to-column connection in a matrix, it typically must use at least one row channel to make the connection. Specifying a channel as a configuration channel allows the instrument driver to use it to create the path. Notice that once a channel has been configured as a configuration channel, then no operation can accept this channel name except for pi40iv_getattribute and pi40iv_setattribute for this attribute only. Note: If you connect a path from x1 to y1 to x2 with the pi40iv_setpath function you need to set y1 as a configuration channel. Example: vicheckerr(pi40iv_setattributeviboolean (vi, "y1", PI40IV_ATTR_IS_CONFIGURATION_CHANNEL,VI_TRUE)); vicheckerr(pi40iv_setpath(vi, "x1->y1,y1->x2")); Otherwise the SetPath function will fail. Prefix info - IviSwtch or pi40iv All IVI driver attributes and functions have a prefix. When the prefix is pi40iv it means that the driver is called directly from the test program. If IviSwtch is used as a prefix then the driver is called through the switch class driver. This is necessary for the testprogram to optain interchangeability. To use the switch class driver, a virtual instrument need to be created, see more below under "Created IVI samples in NI MAX". Created IVI samples in NI MAX When running the installer program a Pickering sample device is created in National Instruments MAX. Under IVI Instruments in NI MAX an entry in Instrument Drivers, Logical Names and Virtual Instruments is created. To use your switch configured here you need to also add an entry for Devices (under IVI Instruments). You then need to choose the created device for your virtual instrument entry. Also the correct driver optionstring need to be added for the virtual instrument. The virtual instrument is given a logical name, this is the name you call when using the switch class driver. The switch class driver uses this to determine which driver dll to call. In our case this is pi40iv32.dll which is the Pickering PXI IVI driver dll. 167 / 208

172 Multiplex Specific Requirements Additional Information for Multiplexer (MUX/MUX-M) Cards. The IVI specification includes support for MUX (multi to single connections), but does not provide for MUX devices with a default connection path, or MUX-M (Multi to Multi connection) devices. For this reason we have added custom Pickering support to the IVI driver allowing Pickering MUX(-M) devices to be fully controlled using the IVI interface. This feature is called "DisMuxCheck" and it disables the IVI connection checking for MUX(-M) devices. MUX-M (Multi to Multi connection) Since the IVI driver defines Multiplexers to have a one to one connection (COM to Ch1 OR COM to Ch 2), the custom feature DisMuxCheck has been implemented which disables IVI checks for a MUX s one to one connection resulting in a Full Multiplexer- Multiconnection functionality. The DisMuxCheck feature is Invoked by amending the option string OptionString=Model=40-xxx-xxx;DisMuxCheck. C Programming example: ViString optionstring = Simulate=0,RangeCheck=1,QueryInstrStatus=0,Cache=1, DriverSetup=Model: ;DisMuxCheck ; pi40iv_connect(vi, com, ch1 ); //connect CH1 to the COM pi40iv_connect(vi, com, ch2 ); //also connect CH2 to the COM (without DisMuxCheck this would fail because COM is already connected to CH1) NI-MAX and NI-Switch Executive example: It can also be implemented in NI- MAX and NI-Switch Executive under Driver Session. In Driver Setup add Model :40-xxx-xxx;DisMuxCheck to enable this feature. MUX devices with a default connection Some MUX devices have a default hardware connection at "power up" or when in a disconnected state. Let us assume we are using a MUX device which is connected by default to channel 5. To first connect COM to channel 1 and then connect to channel 2 we would use the following C code: pi40iv_connect(vi, com, ch1 ); //connect channel 1 to COM pi40iv_disconnect(vi, com, ch1 ); //disconnect channel 1 from COM (this will connect 168 / 208