NI DMM Utility Functions

Utility Functions

• niDMM_reset
• niDMM_ResetWithDefaults
• niDMM_self_test
• niDMM_revision_query
• niDMM_Disable
• niDMM_GetChannelName
• niDMM_ClearError
• niDMM_GetError
• niDMM_GetErrorMessage
• niDMM_LockSession
• niDMM_UnlockSession
• niDMM_GetNextInterchangeWarning
• niDMM_ClearInterchangeWarnings
• niDMM_ResetInterchangeCheck
• niDMM_GetNextCoercionRecord

niDMM_reset

ViStatus = niDMM_reset(ViSession Instrument_Handle)

Purpose

Resets the instrument to a known state and sends initialization commands to the instrument. The initialization commands set instrument settings to the state necessary for the operation of the instrument driver.

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_ResetWithDefaults

ViStatus = niDMM_ResetWithDefaults(ViSession Instrument_Handle)

Purpose

Resets the instrument to a known state and sends initialization commands to the DMM. The initialization commands set the DMM settings to the state necessary for the operation of NI-DMM. All user-defined default values associated with a logical name are applied after setting the DMM.

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_self_test

ViStatus = niDMM_self_test(ViSession Instrument_Handle, ViInt16 *Self_Test_Result, ViChar Self_-_Test_Message[])

Purpose

Performs a self-test on the DMM to ensure that the DMM is functioning properly. Self-test does not calibrate the DMM.

Note  This function calls niDMM_reset, and any configurations previous to the call will be lost. All attributes will be set to their default values after the call returns.

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
Self_Test_Result	ViInt16*	Contains the value returned from the instrument self-test. Zero indicates success. On the NI 4080/4082 and NI 4070/4072, the error code 1013 indicates that you should check the fuse and replace it, if necessary.

Note  Self-test does not check the fuse on the NI 4065, NI 4071, and NI 4081. Hence, even if the fuse is blown on the device, self-test does not return error code 1013.|

Output
Name	Type	Description
Self_-_Test_Message	ViChar[ ]	This parameter contains the string returned from the instrument self-test. The array must contain at least 256 elements. For the NI 4050 and NI 4060, the error codes returned for self-test failures include the following: - NIDMM_ERROR_AC_TEST_FAILURE - NIDMM_ERROR_DC_TEST_FAILURE - NIDMM_ERROR_RESISTANCE_TEST_FAILURE These error codes indicate that the DMM should be repaired. For the NI 4080/4081/4082 and the NI 4070/4071/4072, the error code returned for a self-test failure is NIDMM_ERROR_SELF_TEST_FAILURE. This error code indicates that the DMM should be repaired.

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_revision_query

ViStatus = niDMM_revision_query(ViSession Instrument_Handle, ViChar Instrument_Driver_Revision[], ViChar Firmware_Revision[])

Purpose

Returns the revision numbers of the instrument driver and instrument firmware.

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
Instrument_Driver_Revision	ViChar[]	Returns a string containing the instrument driver software revision numbers.

Note   The array must contain at least 256 elements ViChar[256].

Output
Name	Type	Description
Firmware_Revision	ViChar[]	Returns a string containing the instrument Firmware_Revision numbers.

Note   The array must contain at least 256 elements ViChar[256].

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_Disable

ViStatus = niDMM_Disable(ViSession Instrument_Handle)

Purpose

Places the instrument in a quiescent state where it has minimal or no impact on the system to which it is connected. If a measurement is in progress when this function is called, the measurement is aborted.

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_GetChannelName

ViStatus = niDMM_GetChannelName(ViSession Instrument_Handle, ViInt32 Index, ViInt32 Buffer_Size, ViChar Channel_String[])

Purpose

Returns the Channel_String that is in the channel table at an Index you specify. Not applicable to National Instruments DMMs. Included for compliance with the IviDmm Class Specification.

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.
Index	ViInt32	A 1–based Index into the channel table.
Buffer_Size	ViInt32	Passes the number of bytes in the ViChar array you specify for the Channel_String parameter. If the next Channel_String, including the terminating NULL byte, contains more bytes than you indicate in this parameter, the function copies Buffer_Size –1 bytes into the buffer, places an ASCII NULL 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_String buffer parameter. The default value is None.
Output
Name	Type	Description
Channel_String	ViChar[ ]	Returns the Channel_String that is in the channel table at the Index you specify. Do not modify the contents of the Channel_String.

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_ClearError

ViStatus = niDMM_ClearError(ViSession Instrument_Handle)

Purpose

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.

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_GetError

ViStatus = niDMM_GetError(ViSession Instrument_Handle, ViStatus *Error Code, ViInt32 Buffer_Size, ViChar Description[])

Purpose

Returns the error information associated with the Instrument_Handle. This function retrieves and then clears the error information for the session. If you leave the Instrument_Handle unwired, this function retrieves and then clears the error information for the process.

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.
Buffer_Size	ViInt32	Passes the number of bytes in the ViChar array you specify for the Description parameter. If the error description, including the terminating NULL byte, contains more bytes than you indicate in this parameter, the function copies Buffer_Size –1 bytes into the buffer, places an ASCII NULL 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. The default value is None.
Output
Name	Type	Description
Error_Code	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.
Description	ViChar[]	Returns the error Description for the IVI session or execution thread. If there is no Description, 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 you pass 0 for the Buffer_Size, you can pass VI_NULL for this parameter.

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_GetErrorMessage

ViStatus = niDMM_GetErrorMessage (ViSession Instrument_Handle, ViStatus Error_Code, ViInt32 Buffer_Size, ViChar Error_Message[])

Purpose

Returns the Error_Message as a user-readable string for the provided Error_Code. Calling this function with a Buffer_Size of 0 returns the size needed for the Error_Message.

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. You can also use VI_NULL if you do not have a valid Instrument_Handle.
Error_Code	ViStatus	The error code returned from the instrument for which you want to get a user-readable string.
Buffer_Size	ViInt32	Specifies the number of bytes allocated for the Error_Message ViChar array. If the error description that this function returns (including terminating NULL byte) is larger than you indicated in Buffer_Size, the error description will be truncated to fit. If you pass 0 for Buffer_Size, the function returns the buffer size needed for Error_Message.
Output
Name	Type	Description
Error_Message	ViChar[]	Contains the error information formatted into a user-readable string. The buffer must contain at least as many elements as the value you specify with the Buffer_Size parameter. If you pass 0 for Buffer_Size, you can pass VI_NULL for this parameter.

Return Value

Name	Type	Description
Status	ViStatus	Reports the Status of this operation. If the Buffer_Size parameter is 0, the buffer size needed for Error_Message is returned.

niDMM_LockSession

ViStatus = niDMM_LockSession(ViSession Instrument_Handle, ViBoolean *Caller_Has_Lock)

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 application called this function.
• A call to the instrument driver locked the session.
• A call to the IVI Library locked the session.

After your call to this function returns successfully, no other threads can access the instrument session until you call niDMM_UnlockSession.

Use this function and niDMM_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 this function within the same thread.

To completely unlock the session, you must balance each call to this function with a call to niDMM_UnlockSession. If, however, you use the Caller_Has_Lock parameter in all calls to this function and niDMM_UnlockSession within a function, the IVI Library locks the session only once within the function regardless of the number of calls you make to this function. This feature allows you to call niDMM_UnlockSession just once at the end of the 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.
Output
Name	Type	Description
Caller_Has_Lock	ViBoolean*	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. To use this parameter, complete the following steps: 1. Pass the address of a local ViBoolean variable. 2. In the declaration of the local variable, initialize it to VI_FALSE (0). 3. Pass the address of the same local variable to any other calls you make to this function or niDMM_UnlockSession in the same function. The parameter is an input/output parameter. This function and niDMM_UnlockSession, this function does not lock the session again. If the value is VI_FALSE, this function obtains the lock and sets the value of the parameter to VI_TRUE. If the value is VI_FALSE, niDMM_UnlockSession does not attempt to unlock the session. If the value is VI_TRUE, niDMM_UnlockSession releases the lock and sets the value of the parameter to VI_FALSE. Thus, you can, call niDMM_UnlockSession; return error; }

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_UnlockSession

ViStatus = niDMM_UnlockSession(ViSession Instrument_Handle, ViBoolean *Caller_Has_Lock)

Purpose

This function releases a lock that you acquired on an instrument session using niDMM_LockSession. Refer to niDMM_LockSession for additional information on session locks.

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
Caller_Has_Lock	ViBoolean*	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. To use this parameter, complete the following steps: 1. Pass the address of a local ViBoolean variable. 2. In the declaration of the local variable, initialize it to VI_FALSE (0). 3. Pass the address of the same local variable to any other calls you make to niDMM_LockSession or this function in the same function. The parameter is an input/output parameter. niDMM_LockSession, niDMM_LockSession does not lock the session again. If the value is VI_FALSE, niDMM_LockSession; return error; }

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_GetNextInterchangeWarning

ViStatus = niDMM_GetNextInterchangeWarning(ViSession Instrument_Handle, ViInt32 Buffer_Size, ViChar Interchange_Warning[])

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.

The driver performs interchangeability checking when NIDMM_ATTR_INTERCHANGE_CHECK. 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.

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.
Buffer_Size	ViInt32	Passes the number of bytes in the ViChar array you specify for the Interchange_Warning parameter. If the next interchangeability warning string, including the terminating NULL byte, contains more bytes than you indicate in this parameter, the function copies Buffer_Size –1 bytes into the buffer, places an ASCII NULL 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. The default value is None.
Output
Name	Type	Description
Interchange_Warning	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.

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_ClearInterchangeWarnings

ViStatus = niDMM_ClearInterchangeWarnings(ViSession Instrument_Handle)

Purpose

Clears the list of current interchange warnings.

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_ResetInterchangeCheck

ViStatus = niDMM_ResetInterchangeCheck(ViSession Instrument_Handle)

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 NI-DMM 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 niDMM_GetNextInterchangeWarning 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 niDMM_GetNextInterchangeWarning until no more interchangeability warnings are returned. If you are not interested in the content of those warnings, you can call niDMM_ClearInterchangeWarnings.

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_GetNextCoercionRecord

ViStatus = niDMM_GetNextCoercionRecord(ViSession Instrument_Handle, ViInt32 Buffer_Size, ViChar Coercion_Record[])

Purpose

This function returns the coercion information associated with the IVI session, and it retrieves and clears the oldest instance in which NI-DMM coerced a value you specified to another value.

If you set NIDMM_ATTR_RECORD_COERCIONS, NI-DMM keeps a list of all coercions it makes on ViInt32 or ViReal64 values that you pass to NI-DMM functions. Use this function to retrieve information from that list.

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.
Buffer_Size	ViInt32	Passes the number of bytes in the ViChar array you specify for the Coercion_Record parameter. If the next coercion record string, including the terminating NULL byte, contains more bytes than you indicate in this parameter, the function copies Buffer_Size – 1 bytes into the buffer, places an ASCII NULL 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 default value is None.
Output
Name	Type	Description
Coercion_Record	ViChar[]	Returns the next Coercion_Record for the IVI session. If there are no coercions 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.

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.