NI DMM Acquisition Functions

Acquisition Functions

• niDMM_Read
• niDMM_ReadMultiPoint
• niDMM_ReadWaveform
• niDMM_IsOverRange
• niDMM_IsUnderRange
• niDMM_Initiate
• niDMM_Fetch
• niDMM_FetchMultiPoint
• niDMM_FetchWaveform
• niDMM_Abort
• niDMM_ReadStatus
• niDMM_Control

niDMM_Read

ViStatus = niDMM_Read(ViSession Instrument_Handle, ViInt32 Maximum_Time, ViReal64 *Reading)

Purpose

Acquires a single measurement and returns the measured value.

Parameters

Input
Name	Type	Description
Instrument_Handle	ViSession	Identifies a particular instrument session. You obtain the Instrument_Handle parameter from niDMM_init or niDMM_InitWithOptions. The default is None.
Maximum_Time	ViInt32	Specifies the Maximum_Time allowed for this function to complete in milliseconds. If the function does not complete within this time interval, the function returns the NIDMM_ERROR_MAX_TIME_EXCEEDED error code. This may happen if an external trigger has not been received, or if the specified timeout is not long enough for the acquisition to complete.The valid range is 0–86400000. The default value is NIDMM_VAL_TIME_LIMIT_AUTO (-1). The DMM calculates the timeout automatically.
Output
Name	Type	Description
Reading	ViReal64*	The measured value returned from the DMM.

Return Value

Name	Type	Description
Status	ViStatus	Reports the Status of this operation. To obtain a text description of the status code, call niDMM_GetErrorMessage. To obtain additional information concerning the error condition, use niDMM_GetError.

niDMM_ReadMultiPoint

ViStatus = niDMM_ReadMultiPoint(ViSession Instrument_Handle, ViInt32 Maximum_Time, ViInt32 Array_Size, ViReal64 Reading_Array[], ViInt32 *Actual_Number_Of_Points)

Purpose

Acquires multiple measurements and returns an array of measured values. The number of measurements the DMM makes is determined by the values you specify for the Trigger_Count and Sample_Count parameters in niDMM_ConfigureMultiPoint.

Parameters

Input
Name	Type	Description
Instrument_Handle	ViSession	Identifies a particular instrument session. You obtain the Instrument_Handle parameter from niDMM_init or niDMM_InitWithOptions. The default is None.
Maximum_Time	ViInt32	Specifies the Maximum_Time allowed for this function to complete in milliseconds. If the function does not complete within this time interval, the function returns the NIDMM_ERROR_MAX_TIME_EXCEEDED error code. This may happen if an external trigger has not been received, or if the specified timeout is not long enough for the acquisition to complete.The valid range is 0–86400000. The default value is NIDMM_VAL_TIME_LIMIT_AUTO (-1). The DMM calculates the timeout automatically.
Array_Size	ViInt32	Specifies the number of measurements to acquire. The maximum number of measurements for a finite acquisition is the (Trigger Count x Sample Count) parameters in niDMM_ConfigureMultiPoint. For continuous acquisitions, up to 100,000 points can be returned at once. The number of measurements can be a subset. The valid range is any positive ViInt32. The default value is 1.
Output
Name	Type	Description
Reading_Array	ViReal64[]	An array of measurement values.

Note The size of the Reading_Array must be at least the size that you specify for the Array_Size parameter

Input
Name	Type	Description
Actual_Number_Of_Points	ViInt32*	Indicates the number of measured values actually retrieved from the DMM.

Return Value

Name	Type	Description
Status	ViStatus	Reports the Status of this operation. To obtain a text description of the status code, call niDMM_GetErrorMessage. To obtain additional information concerning the error condition, use niDMM_GetError.

niDMM_ReadWaveform

ViStatus = niDMM_ReadWaveform(ViSession Instrument_Handle, ViInt32 Maximum_Time, ViInt32 Array_Size, ViReal64 Waveform_Array[], ViInt32 *Actual_Number_Of_Points)

Purpose

For the NI 4080/4081/4082 and the NI 4070/4071/4072, acquires a waveform and returns data as an array of values or as a waveform data type. The number of elements in the Waveform_Array is determined by the values you specify for the Waveform_Points parameter in niDMM_ConfigureWaveformAcquisition.

Parameters

Input
Name	Type	Description
Instrument_Handle	ViSession	Identifies a particular instrument session. You obtain the Instrument_Handle parameter from niDMM_init or niDMM_InitWithOptions. The default is None.
Maximum_Time	ViInt32	Specifies the Maximum_Time allowed for this function to complete in milliseconds. If the function does not complete within this time interval, the function returns the NIDMM_ERROR_MAX_TIME_EXCEEDED error code. This may happen if an external trigger has not been received, or if the specified timeout is not long enough for the acquisition to complete.The valid range is 0–86400000. The default value is NIDMM_VAL_TIME_LIMIT_AUTO (-1). The DMM calculates the timeout automatically.
Array_Size	ViInt32	Specifies the number of waveform points to return. You specify the total number of points that the DMM acquires in the Waveform Points parameter of niDMM_ConfigureWaveformAcquisition. The default value is 1.
Output
Name	Type	Description
Waveform_Array	ViReal64[]	An array of measurement values.

Note The size of the Waveform_Array must be at least the size that you specify for the Array_Size parameter

Input
Name	Type	Description
Actual_Number_Of_Points	ViInt32*	Indicates the number of measured values actually retrieved from the DMM.

Return Value

Name	Type	Description
Status	ViStatus	Reports the Status of this operation. To obtain a text description of the status code, call niDMM_GetErrorMessage. To obtain additional information concerning the error condition, use niDMM_GetError.

niDMM_IsOverRange

ViStatus = niDMM_IsOverRange(ViSession Instrument_Handle, ViReal64 Measurement_Value, ViBoolean *Is_Over_Range)

Purpose

Takes a Measurement_Value and determines if the value is a valid measurement or a value indicating that an overrange condition occurred.

Parameters

Input
Name	Type	Description
Instrument_Handle	ViSession	Identifies a particular instrument session. You obtain the Instrument_Handle parameter from niDMM_init or niDMM_InitWithOptions. The default is None.
Measurement_Value	ViReal64	The measured value returned from the DMM.

Note If an overrange condition occurs, the Measurement_Value contains an IEEE-defined NaN (Not a Number) value

Output
Name	Type	Description
Is_Over_Range	ViBoolean*	Returns whether the measurement value is a valid measurement or an overrange condition.

VI_TRUE	1	The value indicates that an overrange condition occurred.
VI_FALSE	0	The value is a valid measurement.

Return Value

Name	Type	Description
Status	ViStatus	Reports the Status of this operation. To obtain a text description of the status code, call niDMM_GetErrorMessage. To obtain additional information concerning the error condition, use niDMM_GetError.

niDMM_IsUnderRange

ViStatus = niDMM_IsUnderRange(ViSession Instrument_Handle, ViReal64 Measurement_Value, ViBoolean *Is_Under_Range)

Purpose

Takes a Measurement_Value and determines if the value is a valid measurement or a value indicating that an underrange condition occurred.

Parameters

Input
Name	Type	Description
Instrument_Handle	ViSession	Identifies a particular instrument session. You obtain the Instrument_Handle parameter from niDMM_init or niDMM_InitWithOptions. The default is None.
Measurement_Value	ViReal64	The measured value returned from the DMM.

Note If an overrange condition occurs, the Measurement_Value contains an IEEE-defined NaN (Not a Number) value

Output
Name	Type	Description
Is_Under_Range	ViBoolean*	Returns whether the Measurement_Value is a valid measurement or an underrange condition.

VI_TRUE	1	The value indicates that an underrange condition occurred.
VI_FALSE	0	The value is a valid measurement.

Return Value

Name	Type	Description
Status	ViStatus	Reports the Status of this operation. To obtain a text description of the status code, call niDMM_GetErrorMessage. To obtain additional information concerning the error condition, use niDMM_GetError.

niDMM_Initiate

ViStatus = niDMM_Initiate(ViSession Instrument_Handle)

Purpose

Initiates an acquisition. After you call this function, the DMM leaves the Idle state and enters the Wait-for-Trigger state. If trigger is set to Immediate mode, the DMM begins acquiring measurement data. Use niDMM_Fetch , niDMM_FetchMultiPoint , or niDMM_FetchWaveform to retrieve the measurement data.

Parameters

Input
Name	Type	Description
Instrument_Handle	ViSession	Identifies a particular instrument session. You obtain the Instrument_Handle parameter from niDMM_init or niDMM_InitWithOptions. The default is None.

Return Value

Name	Type	Description
Status	ViStatus	Reports the Status of this operation. To obtain a text description of the status code, call niDMM_GetErrorMessage. To obtain additional information concerning the error condition, use niDMM_GetError.

niDMM_Fetch

niDMM_Fetch(ViSession Instrument_Handle, ViInt32 Maximum_Time, ViReal64 *Reading)

Purpose

Returns the value from a previously initiated measurement. You must call niDMM_Initiate before calling this function.

Parameters

Input
Name	Type	Description
Instrument_Handle	ViSession	Identifies a particular instrument session. You obtain the Instrument_Handle parameter from niDMM_init or niDMM_InitWithOptions. The default is None.
Maximum_Time	ViInt32	Specifies the Maximum_Time allowed for this function to complete in milliseconds. If the function does not complete within this time interval, the function returns the NIDMM_ERROR_MAX_TIME_EXCEEDED error code. This may happen if an external trigger has not been received, or if the specified timeout is not long enough for the acquisition to complete.The valid range is 0–86400000. The default value is NIDMM_VAL_TIME_LIMIT_AUTO (-1). The DMM calculates the timeout automatically.
Output
Name	Type	Description
Reading	ViReal64*	The measured value returned from the DMM.

Return Value

Name	Type	Description
Status	ViStatus	Reports the Status of this operation. To obtain a text description of the status code, call niDMM_GetErrorMessage. To obtain additional information concerning the error condition, use niDMM_GetError.

niDMM_FetchMultiPoint

ViStatus = niDMM_FetchMultiPoint(ViSession Instrument_Handle, ViInt32 Maximum_Time, ViInt32 Array_Size, ViReal64 Reading_Array[], ViInt32 *Actual_Number_Of_Points)

Purpose

Returns an array of values from a previously initiated multipoint measurement. The number of measurements the DMM makes is determined by the values you specify for the Trigger_Count and Sample_Count parameters of niDMM_ConfigureMultiPoint. You must first call niDMM_Initiate to initiate a measurement before calling this function.

Parameters

Input
Name	Type	Description
Instrument_Handle	ViSession	Identifies a particular instrument session. You obtain the Instrument_Handle parameter from niDMM_init or niDMM_InitWithOptions. The default is None.
Maximum_Time	ViInt32	Specifies the Maximum_Time allowed for this function to complete in milliseconds. If the function does not complete within this time interval, the function returns the NIDMM_ERROR_MAX_TIME_EXCEEDED error code. This may happen if an external trigger has not been received, or if the specified timeout is not long enough for the acquisition to complete.The valid range is 0–86400000. The default value is NIDMM_VAL_TIME_LIMIT_AUTO (-1). The DMM calculates the timeout automatically.
Array_Size	ViInt32	Specifies the number of measurements to acquire. The maximum number of measurements for a finite acquisition is the (Trigger Count x Sample Count) parameters in niDMM_ConfigureMultiPoint. For continuous acquisitions, up to 100,000 points can be returned at once. The number of measurements can be a subset. The valid range is any positive ViInt32. The default value is 1.
Output
Name	Type	Description
Reading_Array	ViReal64[]	An array of measurement values.

Note The size of the Reading_Array must be at least the size that you specify for the Array_Size parameter

Input
Name	Type	Description
Actual_Number_Of_Points	ViInt32*	Indicates the number of measured values actually retrieved from the DMM.

Return Value

Name	Type	Description
Status	ViStatus	Reports the Status of this operation. To obtain a text description of the status code, call niDMM_GetErrorMessage. To obtain additional information concerning the error condition, use niDMM_GetError.

niDMM_FetchWaveform

ViStatus = niDMM_FetchWaveform(ViSession Instrument_Handle, ViInt32 Maximum_Time, ViInt32 Array_Size, ViReal64 Waveform_Array[], ViInt32 *Actual_Number_Of_Points)

Purpose

For the NI 4080/4081/4082 and the NI 4070/4071/4072, returns an array of values from a previously initiated waveform acquisition. You must call niDMM_Initiate before calling this function.

Parameters

Input
Name	Type	Description
Instrument_Handle	ViSession	Identifies a particular instrument session. You obtain the Instrument_Handle parameter from niDMM_init or niDMM_InitWithOptions. The default is None.
Maximum_Time	ViInt32	Specifies the Maximum_Time allowed for this function to complete in milliseconds. If the function does not complete within this time interval, the function returns the NIDMM_ERROR_MAX_TIME_EXCEEDED error code. This may happen if an external trigger has not been received, or if the specified timeout is not long enough for the acquisition to complete.The valid range is 0–86400000. The default value is NIDMM_VAL_TIME_LIMIT_AUTO (-1). The DMM calculates the timeout automatically.
Array_Size	ViInt32	Specifies the number of waveform points to return. You specify the total number of points that the DMM acquires in the Waveform Points parameter of niDMM_ConfigureWaveformAcquisition. The default value is 1.
Output
Name	Type	Description
Waveform_Array	ViReal64 []	Waveform Array is an array of measurement values stored in waveform data type.
Actual_Number_Of_Points	ViInt32*	Indicates the number of measured values actually retrieved from the DMM.

Return Value

Name	Type	Description
Status	ViStatus	Reports the Status of this operation. To obtain a text description of the status code, call niDMM_GetErrorMessage. To obtain additional information concerning the error condition, use niDMM_GetError.

niDMM_Abort

ViStatus = niDMM_Abort(ViSession Instrument_Handle)

Purpose

Aborts a previously initiated measurement and returns the DMM to the Idle state.

Parameters

Input
Name	Type	Description
Instrument_Handle	ViSession	Identifies a particular instrument session. You obtain the Instrument_Handle parameter from niDMM_init or niDMM_InitWithOptions. The default is None.

Return Value

Name	Type	Description
Status	ViStatus	Reports the Status of this operation. To obtain a text description of the status code, call niDMM_GetErrorMessage. To obtain additional information concerning the error condition, use niDMM_GetError.

niDMM_ReadStatus

ViStatus = niDMM_ReadStatus(ViSession Instrument_Handle, ViInt32 *Acquisition_Backlog, ViInt16 *Acquisition_Status)

Purpose

Returns measurement backlog and acquisition status. Use this function to determine how many measurements are available before calling niDMM_Fetch, niDMM_FetchMultipoint, or niDMM_FetchWaveform.

Note The NI 4050 is not supported

Parameters

Input
Name	Type	Description
Instrument_Handle	ViSession	Identifies a particular instrument session. You obtain the Instrument_Handle parameter from niDMM_init or niDMM_InitWithOptions. The default is None.
Output
Name	Type	Description
Acquisition_Backlog	ViInt32*	The number of measurements available to be read. If the backlog continues to increase, data is eventually overwritten, resulting in an error.

Note On the NI 4060, the Backlog does not increase when autoranging. On the NI 4065, the Backlog does not increase when Range is set to AUTO RANGE ON (-1), or before the first point is fetched when Range is set to AUTO RANGE ONCE (-3). These behaviors are due to the autorange model of the devices.

Output
Name	Type	Description
Acquisition_Status	ViInt16*	Indicates status of the acquisition. The following table shows the acquisition states:

0	Running
1	Finished with backlog
2	Finished with no backlog
3	Paused
4	No acquisition in progress

Return Value

Name	Type	Description
Status	ViStatus	Reports the Status of this operation. To obtain a text description of the status code, call niDMM_GetErrorMessage. To obtain additional information concerning the error condition, use niDMM_GetError.

niDMM_Control

ViStatus = niDMM_Control(ViSession Instrument_Handle, ViInt32 Control_Action)

Purpose

Controls the DMM. Use this function if you want a parameter change to be immediately reflected in the hardware. Use this function before calling niDMM_Initiate to make the initiate call as quickly as possible.

Notes The NI 4050 and NI 4060 are not supported.

Calling this function while the DMM is taking measurements results in an error. After the DMM is finished taking measurements, calling this function will make any unfetched data points unavailable.

Parameters

Input
Name	Type	Description
Instrument_Handle	ViSession	Identifies a particular instrument session. You obtain the Instrument_Handle parameter from niDMM_init or niDMM_InitWithOptions. The default is None.
Control Action	ViInt32	The action you want the driver to perform. Only NIDMM_VAL_CONTROL_COMMIT (0) is supported, which commits to hardware all of the configured attributes associated with the session.

Return Value

Name	Type	Description
Status	ViStatus	Reports the Status of this operation. To obtain a text description of the status code, call niDMM_GetErrorMessage. To obtain additional information concerning the error condition, use niDMM_GetError.