Skip to content

NI DCPOWER Utility Functions

Jump to bottom
Siddhartha Ray edited this page Apr 20, 2021 · 2 revisions

Utility Functions

niDCPower_Disable

ViStatus niDCPower_Disable(ViSession vi);

Purpose

This function performs the same actions as the niDCPower_ResetWithChannels function, except that this function also immediately sets the NIDCPOWER_ATTR_OUTPUT_ENABLED attribute to VI_FALSE.

This function opens the output relay on instruments that have an output relay.

This function applies to all channels and instruments in the session.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.

Return Value

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

niDCPower_ResetWithChannels

ViStatus niDCPower_ResetWithChannels(ViSession vi);

Purpose

Resets the specified channel(s) to a known state. This function disables power generation, resets channel attributes to their default values, commits the channel attributes, and leaves the channel(s) in the Uncommitted state.

Related topics:

Programming States

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
channelName ViConstString

Specifies the channel(s) to use. Specify the channel(s) using the form PXI1Slot3/0,PXI1Slot3/2-3,PXI1Slot4/2-3 or PXI1Slot3/0,PXI1Slot3/2:3,PXI1Slot4/2:3, where PXI1Slot3 and PXI1Slot4 are instrument resource names and 0, 2, and 3 are channels.

If you pass "" for this control, all channels in the session are used.

Return Value

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

niDCPower_reset

ViStatus niDCPower_reset(ViSession vi);

Purpose

This function is deprecated. Use niDCPower_ResetWithChannels instead.

Resets the device to a known state. This function disables power generation, resets session attributes to their default values, commits the session attributes, and leaves the session in the Uncommitted state. Refer to the Programming States topic for more information about NI-DCPower software states.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.

Return Value

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

niDCPower_ResetDevice

ViStatus niDCPower_ResetDevice(ViSession vi);

Purpose

Resets all instruments in the session to a known state. The function disables power generation, resets all attributes for all instruments included in the session to their default values, clears errors such as overtemperature and unexpected loss of auxiliary power, commits the instrument attributes, and leaves the instrument(s) in the Uncommitted state. This function also performs a hard reset on the instrument(s) and driver software. This function has the same functionality as using reset in Measurement & Automation Explorer (MAX).

This also opens the output relay on instruments that have an output relay.

Related topics:

Programming States

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.

Return Value

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

niDCPower_self_test

ViStatus niDCPower_self_test(ViSession vi, ViInt16 *selfTestResult, ViChar selfTestMessage);

Purpose

Performs the device self-test routine and returns the test result(s). Calling this function implicitly calls the niDCPower_ResetWithChannels function.

When calling this function with the PXIe-4162/4163, specify all channels of your PXIe-4162/4163 with the resourceName input of the niDCPower_InitializeWithIndependentChannels function. You cannot self test a subset of PXIe-4162/4163 channels.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
Output
Name Type Description
selfTestResult ViInt16* Returns the value result from the device self-test.
Self-Test Code Description
0 Self test passed.
1 Self test failed.
selfTestMessage ViChar Returns the self-test result message. The size of this array must be at least 256 bytes.

Return Value

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

niDCPower_ImportAttributeConfigurationFile

ViStatus niDCPower_ImportAttributeConfigurationFile(ViSession vi, ViConstString filePath);

Purpose

Imports a configuration to the session from the specified file.

You can export and import supported configurations only between NIDCPower devices with identical model numbers and the same number of configured channels.

!Note Note  You cannot call this function while any channel is in the Running state.
Supported Configurations

You can export and import the following configurations between NIDCPower sessions:

  • Attribute configurations
  • Advanced sequences

Support for this Function

You must set the session source mode to NIDCPOWER_VAL_SEQUENCE in order to configure or export and import advanced sequences.

Configuration exports from sessions created with the niDCPower_InitializeWithIndependentChannels function cannot be imported into sessions created with deprecated initialize functions.

!Note Note  Exporting and importing simple sequences in Sequence source mode is unsupported.
Channel Mapping Behavior

When importing and exporting session attribute configurations between NIDCPower sessions that were initialized with different channels, the configurations of the exporting channels are mapped to the importing channels based on the order of the resources you specify in the resourceName input to the niDCPower_InitializeWithIndependentChannels function.

Refer to Import/Export Attribute Configuration Mapping Behavior for details.

Related Topics:

Programming States

Using Properties and Attributes

Setting Properties and Attributes Before Reading Them

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
filePath ViConstString The absolute path to the file that contains the configuration to import. If you specify an empty or relative path, this function returns an error.

Default File Extension: .nidcpowerconfig

Return Value

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

niDCPower_ExportAttributeConfigurationFile

ViStatus niDCPower_ExportAttributeConfigurationFile(ViSession vi, ViConstString filePath);

Purpose

Exports a session configuration to the specified file.

You can export and import supported configurations only between NIDCPower devices with identical model numbers and the same number of configured channels.

This function verifies that the attributes you have configured for the session are valid. If the configuration is invalid, NIDCPower returns an error.

Supported Configurations

You can export and import the following configurations between NIDCPower sessions:

  • Attribute configurations
  • Advanced sequences

Support for this Function

You must set the source mode to NIDCPOWER_VAL_SEQUENCE in order to configure or export and import advanced sequences.

Configuration exports from sessions created with the niDCPower_InitializeWithIndependentChannels function cannot be imported into sessions created with deprecated initialize functions.

!Note Note  Exporting and importing simple sequences in Sequence source mode is unsupported.
Channel Mapping Behavior

When importing and exporting session attribute configurations between NIDCPower sessions that were initialized with different channels, the configurations of the exporting channels are mapped to the importing channels based on the order of the resources you specify in the resourceName input to the niDCPower_InitializeWithIndependentChannels function.

Refer to Import/Export Attribute Configuration Mapping Behavior for details.

Related Topics:

Using Properties and Attributes

Setting Properties and Attributes Before Reading Them

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
filePath ViConstString The absolute path to a placeholder file you must create to contain the configuration you want to export. If you specify an empty or relative path, this function returns an error.

Default file extension: .nidcpowerconfig

Return Value

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

niDCPower_ImportAttributeConfigurationBuffer

ViStatus niDCPower_ImportAttributeConfigurationBuffer (ViSession vi, ViInt32 size, ViAddr configuration);

Purpose

Imports a configuration to the session from the specified buffer.

You can export and import supported configurations only between NIDCPower devices with identical model numbers and the same number of configured channels.

!Note Note  You cannot call this function while any channel is in the Running state.
Supported Configurations

You can export and import the following configurations between NIDCPower sessions:

  • Attribute configurations
  • Advanced sequences

Support for this Function

You must set the source mode to NIDCPOWER_VAL_SEQUENCE in order to configure or export and import advanced sequences.

Configuration exports from sessions created with the niDCPower_InitializeWithIndependentChannels function cannot be imported into sessions created with deprecated initialize functions.

!Note Note  Exporting and importing simple sequences in Sequence source mode is unsupported.
Channel Mapping Behavior

When importing and exporting session attribute configurations between NIDCPower sessions that were initialized with different channels, the configurations of the exporting channels are mapped to the importing channels based on the order of the resources you specify in the resourceName input to the niDCPower_InitializeWithIndependentChannels function.

Refer to Import/Export Attribute Configuration Mapping Behavior for details.

Related Topics:

Programming States

Using Properties and Attributes

Setting Properties and Attributes Before Reading Them

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
size ViInt32 Specifies the size, in bytes, of the byte array to import. If you enter 0, this function returns the needed size.
configuration ViAddr Specifies the byte array buffer that contains the attribute configuration to import.

Return Value

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

niDCPower_ExportAttributeConfigurationBuffer

ViStatus niDCPower_ExportAttributeConfigurationBuffer (ViSession vi, ViInt32 size, ViAddr configuration);

Purpose

Exports a session configuration to a buffer.

You can export and import supported configurations only between NIDCPower devices with identical model numbers and the same number of configured channels.

This function verifies that the attributes you have configured for the session are valid. If the configuration is invalid, NIDCPower returns an error.

Supported Configurations

You can export and import the following configurations between NIDCPower sessions:

  • Attribute configurations
  • Advanced sequences

Support for this Function

You must set the source mode to NIDCPOWER_VAL_SEQUENCE in order to configure or export and import advanced sequences.

Configuration exports from sessions created with the niDCPower_InitializeWithIndependentChannels function cannot be imported into sessions created with deprecated initialize functions.

!Note Note  Exporting and importing simple sequences in Sequence source mode is unsupported.
Channel Mapping Behavior

When importing and exporting session attribute configurations between NIDCPower sessions that were initialized with different channels, the configurations of the exporting channels are mapped to the importing channels based on the order of the resources you specify in the resourceName input to the niDCPower_InitializeWithIndependentChannels function.

Refer to Import/Export Attribute Configuration Mapping Behavior for details.

Related Topics:

Using Properties and Attributes

Setting Properties and Attributes Before Reading Them

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
size ViInt32 Specifies the size, in bytes, of the byte array to export. If you enter 0, this function returns the needed size.
configuration ViAddr Specifies the byte array buffer to be populated with the exported attribute configuration.

Return Value

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

niDCPower_revision_query

ViStatus niDCPower_revision_query(ViSession vi, ViChar instrumentDriverRevision, ViChar firmwareRevision);

Purpose

Returns the revision information of NI-DCPower and the device firmware.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
Output
Name Type Description
instrumentDriverRevision ViChar

Returns the driver revision information for NI-DCPower.

In multi-instrument sessions, this function returns an error if any instruments have different firmware revisions. In this case, instead of using this function, read the NIDCPOWER_ATTR_INSTRUMENT_FIRMWARE_REVISION attribute for the instrument you specify.
firmwareRevision ViChar Returns firmware revision information for the device you are using. The size of this array must be at least 256 bytes.

Return Value

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

niDCPower_ResetWithDefaults

ViStatus niDCPower_ResetWithDefaults(ViSession vi);

Purpose

Resets all channels in the session to a known state. This function disables power generation, resets session attributes to their default values, commits the session attributes, and leaves the session in the Running state. In addition to exhibiting the behavior of the niDCPower_ResetWithChannels function, this function can assign user-defined default values for configurable attributes from the IVI configuration.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.

Return Value

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

niDCPower_GetChannelName

ViStatus niDCPower_GetChannelName(ViSession vi, ViInt32 index, ViInt32 bufferSize, ViChar channelName);

Purpose

Returns channel name(s) from a one-based index. Use the NIDCPOWER_ATTR_CHANNEL_COUNT attribute to determine the upper bound of valid values for index.

Use this function to identify the fully qualified names of channels. Fully qualified channel names are required to access channels in multi-instrument sessions.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
index ViInt32 Specifies which output channel name to return. The index values begin at 1.
bufferSize ViInt32 Specifies the number of bytes in the ViChar array you specify for channelName. If the channelName, including the terminating NUL byte, contains more bytes than you indicate in this attribute, 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, you can pass VI_NULL for channelName.
Output
Name Type Description
channelName ViChar Returns a string of the channel name(s).

Return Value

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

niDCPower_GetChannelNameFromString

ViStatus niDCPower_GetChannelNameFromString(ViSession vi, ViInt32 index, ViInt32 bufferSize, ViChar channelName);

Purpose

Returns a comma-separated list of channel names from a string index list.

Use this function to identify the fully qualified names of channels. Fully qualified channel names are required to access channels in multi-instrument sessions.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
index ViChar

Specifies an index list for the channels in the session.

Valid values are from zero to the total number of channels in the session minus one. The index string can be one of the following formats:

- A comma-separated list - for example, "0,2,3,1"

- A range using a hyphen - for example, "0-3"

- A range using a colon - for example, "0:3"

You can combine comma-separated lists and ranges that use a hyphen or colon. Both out-of-order and repeated indices are supported ("2,3,0", "1,2,2,3"). White space characters, including spaces, tabs, feeds, and carriage returns, are allowed between characters. Ranges can be incrementing or decrementing.
bufferSize ViInt32 Specifies the number of bytes in the ViChar array you specify for channelName. If the channelName, including the terminating NUL byte, contains more bytes than you indicate in this attribute, 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, you can pass VI_NULL for channelName.
Output
Name Type Description
channelName ViChar Returns a string of the channel name(s).

Return Value

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

niDCPower_GetNextCoercionRecord

ViStatus niDCPower_GetNextCoercionRecord(ViSession vi, ViInt32 bufferSize, ViChar coercionRecord);

Purpose

Returns the coercion information associated with the IVI session and clears the earliest instance in which NI-DCPower coerced a value you specified.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
bufferSize ViInt32 Specifies the number of bytes in the ViChar array you specify for coercionRecord. If the next coercion record string, including the terminating NUL byte, contains more bytes than you indicate in this attribute, 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, you can pass VI_NULL for coercionRecord.
Output
Name Type Description
coercionRecord ViChar Returns the next coercionRecord for the IVI session. If there are no coercionRecords, the function returns an empty string.

Return Value

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

niDCPower_ClearInterchangeWarnings

ViStatus niDCPower_ClearInterchangeWarnings(ViSession vi);

Purpose

Clears the list of current interchange warnings.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.

Return Value

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

niDCPower_ResetInterchangeCheck

ViStatus niDCPower_ResetInterchangeCheck(ViSession vi);

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 niDCPower_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 niDCPower_GetNextInterchangeWarning function until no more interchangeability warnings are returned. If you are not interested in the content of those warnings, you can call the niDCPower_ClearInterchangeWarnings function.

!Note Note  niDCPower_GetNextInterchangeWarning does not mark any attributes for an interchange check.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.

Return Value

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

niDCPower_GetNextInterchangeWarning

ViStatus niDCPower_GetNextInterchangeWarning(ViSession vi, ViInt32 bufferSize, ViChar interchangeWarning);

Purpose

This function returns the interchangeability warning associated with the IVI session. It retrieves and clears the earliest instance in which the class driver recorded an interchangeability warning. Interchangeability warnings indicate that using your application with a different device may cause a different behavior.

NI-DCPower performs interchangeability checking when the NIDCPOWER_ATTR_INTERCHANGE_CHECK attribute is set to VI_TRUE. This function returns an empty string in warning if no interchangeability warnings remain for the session. In general, NI-DCPower generates interchangeability warnings when an attribute that affects the behavior of the device is in a state that you did not specify.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
bufferSize ViInt32 Specifies the number of bytes in the ViChar array you specify for interchangeWarning. If the next interchangeability warning string, including the terminating NUL byte, contains more bytes than you indicate in this attribute, 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, you can pass VI_NULL for interchangeWarning.
Output
Name Type Description
interchangeWarning ViChar Returns the next interchange warning for the IVI session. If there are no interchange warnings, the function returns an empty string.

Return Value

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

niDCPower_GetError

ViStatus niDCPower_GetError(ViSession vi, ViStatus *code, ViInt32 bufferSize, ViChar description);

Purpose

Retrieves and then clears the IVI error information for the session or the current execution thread unless bufferSize is 0, in which case the function does not clear the error information. By passing 0 for the buffer size, you can ascertain the buffer size required to get the entire error description string and then call the function again with a sufficiently large buffer size.

If the user specifies a valid IVI session for vi, this function retrieves and then clears the error information for the session. If the user passes VI_NULL for vi, this function retrieves and then clears the error information for the current execution thread. If vi 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 niDCPower_GetError or niDCPower_ClearError.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
bufferSize ViInt32 Specifies the number of bytes in the ViChar array you specify for description.

If the error description, including the terminating NUL byte, contains more bytes than you indicate in this attribute, 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 this attribute, you can pass VI_NULL for description.
Output
Name Type Description
Code ViStatus* Returns the error code for the session or execution thread.
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 bufferSize. If the error description, including the terminating NUL byte, contains more bytes than you indicate with bufferSize, 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 bufferSize, you can pass VI_NULL for this attribute.

Return Value

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

niDCPower_ClearError

ViStatus niDCPower_ClearError(ViSession vi);

Purpose

Clears the error code and error description for the IVI session. If the user specifies a valid IVI session for vi, this function clears the error information for the session. If the user passes VI_NULL for vi, this function clears the error information for the current execution thread. If the ViSession 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 niDCPower_GetError function, which occurs when a call to niDCPower_InitializeWithChannels fails.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.

Return Value

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

niDCPower_error_message

ViStatus niDCPower_error_message(ViSession vi, ViStatus errorCode, ViChar errorMessage256);

Purpose

Converts a status code returned by an instrument driver function into a user-readable string.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
errorCode ViStatus Specifies the status parameter that is returned from any of the NI-DCPower functions.
Output
Name Type Description
error_message 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

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

niDCPower_LockSession

ViStatus niDCPower_LockSession(ViSession vi, ViBoolean *callerHasLock);

Purpose

Obtains a multithread lock on the device session. Before doing so, the software waits until all other execution threads release their locks on the device session.

Other threads may have obtained a lock on this session for the following reasons:

  • The application called the niDCPower_LockSession function.
  • A call to NI-DCPower locked the session.
  • A call to the IVI engine locked the session.
  • After a call to the niDCPower_LockSession function returns successfully, no other threads can access the device session until you call the niDCPower_UnlockSession function.
  • Use the niDCPower_LockSession function and the niDCPower_UnlockSession function around a sequence of calls to instrument driver functions if you require that the device retain its settings through the end of the sequence.

You can safely make nested calls to the niDCPower_LockSession function within the same thread. To completely unlock the session, you must balance each call to the niDCPower_LockSession function with a call to the niDCPower_UnlockSession function. If, however, you use Caller_Has_Lock in all calls to the niDCPower_LockSession and niDCPower_UnlockSession function within a function, the IVI Library locks the session only once within the function regardless of the number of calls you make to the niDCPower_LockSession function. This behavior allows you to call the niDCPower_UnlockSession function just once at the end of the function.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
Output
Name Type Description
callerHasLock ViBoolean*

This parameter is optional. 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 the niDCPower_LockSession function or the niDCPower_UnlockSession function in the same function.

The parameter is an input/output parameter. The niDCPower_LockSession and niDCPower_UnlockSession functions each inspect the current value and take the following actions.

- If the value is VI_TRUE, the niDCPower_LockSession function does not lock the session again.

- If the value is VI_FALSE, the niDCPower_LockSession function obtains the lock and sets the value of the parameter to VI_TRUE.

- If the value is VI_FALSE, the niDCPower_UnlockSession function does not attempt to unlock the session.

- If the value is VI_TRUE, the niDCPower_UnlockSession function releases the lock and sets the value of the parameter to VI_FALSE.

Thus, you can, call the niDCPower_UnlockSession function at the end of your function without worrying about whether you actually have the lock, as shown in the following example.

ViStatus TestFunc (ViSession vi, ViInt32 flags)
{
ViStatus error = VI_SUCCESS;
ViBoolean haveLock = VI_FALSE;

if (flags & BIT_1)
{
viCheckErr( niDCPower_LockSession(vi, &haveLock));
viCheckErr( TakeAction1(vi));
if (flags & BIT_2)
{
viCheckErr( niDCPower_UnlockSession(vi, &haveLock));
viCheckErr( TakeAction2(vi));
viCheckErr( niDCPower_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.*/
niDCPower_UnlockSession(vi, &haveLock);
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 the niDCPower_error_message function. To obtain additional information concerning the error condition, call the niDCPower_GetError function.

niDCPower_UnlockSession

ViStatus niDCPower_UnlockSession(ViSession vi, ViBoolean *callerHasLock);

Purpose

Releases a lock that you acquired on an device session using niDCPower_LockSession. Refer to niDCPower_LockSession for additional information on session locks.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_InitializeWithIndependentChannels function.
Output
Name Type Description
callerHasLock ViBoolean*

This attribute is optional. If you do not want to use this attribute, pass VI_NULL.

Use this attribute 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 niDCPower_LockSession or niDCPower_UnlockSessionin the same function.

The parameter is an input/output parameter. niDCPower_LockSession and niDCPower_UnlockSessioneach inspect the current value and take the following actions.

- If the value is VI_TRUE, niDCPower_LockSession does not lock the session again.

- If the value is VI_FALSE, niDCPower_LockSession obtains the lock and sets the value of the parameter to VI_TRUE.

- If the value is VI_FALSE, niDCPower_UnlockSessiondoes not attempt to unlock the session.

- If the value is VI_TRUE, niDCPower_UnlockSessionreleases the lock and sets the value of the parameter to VI_FALSE.

Thus, you can, call niDCPower_UnlockSession at the end of your function without worrying about whether you actually have the lock, as the following example shows.

ViStatus TestFunc (ViSession vi, ViInt32 flags)
{
ViStatus error = VI_SUCCESS;
ViBoolean haveLock = VI_FALSE;

if (flags & BIT_1)
{
viCheckErr( niDCPower_LockSession(vi, &haveLock));
viCheckErr( TakeAction1(vi));
if (flags & BIT_2)
{
viCheckErr( niDCPower_UnlockSession(vi, &haveLock));
viCheckErr( TakeAction2(vi));
viCheckErr( niDCPower_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.*/
niDCPower_UnlockSession(vi, &haveLock);
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 the niDCPower_error_message function. To obtain additional information concerning the error condition, call the niDCPower_GetError function.

Table of Contents

Home

Internal Development

Creating and Setting Up a gRPC Server

Server Security Support

Creating a gRPC Client

gRPC Client Examples

Session Utilities API Reference

Driver Documentation

gRPC API Differences From C API

Sharing Driver Sessions Between Clients

C API Docs
NI-DAQmx
NI-DCPOWER
NI-DIGITAL PATTERN DRIVER
NI-DMM
NI-FGEN
NI-FPGA
NI-RFmx Bluetooth
NI-RFmx NR
NI-RFmx WCDMA
NI-RFmx GSM
NI-RFmx CDMA2k
NI-RFmx Instr
NI-RFmx LTE
NI-RFmx SpecAn
NI-RFmx TD-SCDMA
NI-RFmx WLAN
NI-RFSA
NI-RFSG
NI-SCOPE
NI-SWITCH
NI-TCLK
NI-XNET
Clone this wiki locally