Skip to content

NI SWITCH Utility Functions

Jump to bottom
Kevin Reimnitz edited this page Mar 24, 2021 · 1 revision

Utility Functions

niSwitch_Commit

Specific Function

C Function Prototype

ViStatus niSwitch_Commit (ViSession vi);

Purpose

Downloads the configured scan list and trigger settings to hardware.

Calling niSwitch_Commit is optional as it is implicitly called during niSwitch_InitiateScan. Use niSwitch_Commit to arm triggers in a given order or to control when expensive hardware operations are performed.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.

Related Information

  • niSwitch_InitiateScan
  • Scanning

niSwitch_GetChannelName

IviSwtchBase Capability Group

C Function Prototype

ViStatus niSwitch_GetChannelName (ViSession vi, ViInt32 index, ViInt32 bufferSize, ViChar[] channelNameBuffer);

Purpose

Returns the channel string that is in the channel table at the specified index.

Use niSwitch_GetChannelName in a For Loop to get a complete list of valid channel names for the switch. Use the NISWITCH_ATTR_CHANNEL_COUNT attribute to determine the number of channels.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
index ViInt32 A 1-based index into the channel table. The default value is 1. The maximum value is Value of Channel Count attribute.
bufferSize ViInt32 Pass the number of bytes in the ViChar array you specify for the Channel Name Buffer parameter. If the channel name 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 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 bufferSize 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.
channelNameBuffer ViChar[] Returns the channel name that is in the channel table at the index you specify.

Related Information

  • niSwitch_GetRelayName

niSwitch_reset

Specific Function

C Function Prototype

ViStatus niSwitch_reset (ViSession vi);

Purpose

Disconnects all created paths and returns the switch module to the state at initialization. Configuration channel and source channel settings remain unchanged.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.

Related Information

  • Intialization
  • niSwitch_DisconnectAll

niSwitch_ResetWithDefaults

Specific Function

C Function Prototype

ViStatus niSwitch_ResetWithDefaults (ViSession vi);

Purpose

Resets the switch module and applies initial user specified settings from the logical name used to initialize the session. If the session was created without a logical name, this function is equivalent to niSwitch_reset.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.

Related Information

  • niSwitch_reset
  • Initialization

niSwitch_Disable

Specific Function

C Function Prototype

ViStatus niSwitch_Disable (ViSession vi);

Purpose

Places the switch module in a quiescent state, where it has minimal or no impact on the system to which it is connected. All channels are disconnected and any scan in progress is aborted.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.

Related Information

  • niSwitch_close
  • niSwitch_DisconnectAll

niSwitch_self_test

Specific Function

C Function Prototype

ViStatus niSwitch_self_test (ViSession vi, ViInt16* selfTestResult, ViChar[] selfTestMessage);

Purpose

Verifies that NI-SWITCH can communicate with the switch.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
selfTestResult ViInt16 Value returned from the switch self-test.

0 Passed
1 Failed
selfTestMessage ViChar[] Self-test response string from the switch. You must pass a ViChar array with at least 256 bytes.

Related Information

  • Debugging with the Switch Soft Front Panel

niSwitch_revision_query

Specific Function

C Function Prototype

ViStatus niSwitch_revision_query (ViSession vi, ViChar[] instrumentDriverRevision, ViChar[] firmwareRevision);

Purpose

Returns the revision of the NI-SWITCH driver.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
instrumentDriverRevision ViChar[] NI-SWITCH software revision numbers in the form of a string. You must pass a ViChar array with at least 256 bytes.
firmwareRevision ViChar[] Currently unsupported.

Related Information

  • Firmware Revision

niSwitch_error_query

Specific Function

C Function Prototype

ViStatus niSwitch_error_query (ViSession vi, ViInt32* errorCode, ViChar[] errorMessage);

Purpose

This function reads an error code and a message from the instrument error queue. NI-SWITCH does not have an error queue, so this function never returns any errors.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
errorCode ViInt32 Returns the error code read from the instrument error queue.
NI-SWITCH does not have an error queue, so this function never returns any errors.
errorMessage 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.
NI-SWITCH does not have an error queue, so this function only returns No error.

Related Information

  • Error and Status Codes

niSwitch_error_message

Specific Function

C Function Prototype

ViStatus niSwitch_error_message (ViSession vi, ViStatus errorCode, ViChar[] errorMessage);

Purpose

Converts an error code returned by NI-SWITCH into a user-readable string. Generally this information is supplied in error out of any NI-SWITCH VI. Use niSwitch_error_message for a static lookup of an error code description.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
errorCode ViStatus Status code returned by any NI-SWITCH function. The default value is 0 (VI_SUCCESS).
errorMessage ViChar[] The error information formatted into a string. You must pass a ViChar array with at least 256 bytes.

Related Information

  • Error and Status Codes

niSwitch_InvalidateAllAttributes

Specific Function

C Function Prototype

ViStatus_VI_FUNC niSwitch_InvalidateAllAttributes (VISession Vi);

Purpose

Invalidates the cached values of all attributes for the session.

Parameters

Name Type Description
vi ViSession Unique identifier for an IVI session.

Related Information

  • niSwitch_reset
  • Initialization

niSwitch_GetNextCoercionRecord

Specific Function

C Function Prototype

ViStatus niSwitch_GetNextCoercionRecord (ViSession vi, ViInt32 bufferSize, ViChar[] coercionRecord);

Purpose

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

If you set the NISWITCH_ATTR_RECORD_COERCIONS attribute to VI_TRUE, NI-SWITCH keeps a list of all coercions it makes on ViInt32 or ViReal64 values you pass to NI-SWITCH 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 bufferSize–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 bufferSize is 4, the function places "123" into the buffer and returns 7. 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.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
bufferSize 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 bufferSize–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 bufferSize 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.
coercionRecord 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 bufferSize parameter.
If the next coercion record string, including the terminating NUL byte, contains more bytes than you indicate with the bufferSize parameter, the function copies bufferSize–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 bufferSize 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.

Related Information

  • Record Value Coercions

niSwitch_GetNextInterchangeWarning

Specific Function

C Function Prototype

ViStatus niSwitch_GetNextInterchangeWarning (ViSession vi, ViInt32 bufferSize, ViChar[] interchangeWarning);

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 NISWITCH_ATTR_INTERCHANGE_CHECK attribute is set to VI_TRUE. The function returns an empty string in the interchangeWarning 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

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
bufferSize ViInt32 Pass the number of bytes in the ViChar array you specify for the interchangeWarning parameter.
If the next interchangeability warning string, 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 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 bufferSize 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.
interchangeWarning 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 bufferSize parameter.
If the next interchangeability warning string, including the terminating NUL byte, contains more bytes than you indicate with the bufferSize parameter, the function copies bufferSize–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 bufferSize 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.

Related Information

  • niSwitch_ClearInterchangeWarnings
  • niSwitch_ResetInterchangeCheck

niSwitch_ClearInterchangeWarnings

Specific Function

C Function Prototype

ViStatus niSwitch_ClearInterchangeWarnings (ViSession vi);

Purpose

This function clears the list of current interchange warnings.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.

Related Information

  • niSwitch_GetNextInterchangeWarning
  • niSwitch_ResetInterchangeCheck

niSwitch_ResetInterchangeCheck

Specific Function

C Function Prototype

ViStatus niSwitch_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, ensure 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 instrument state depends on the configuration from a previously executed test module. Therefore, 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 behavior change 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 niSwitch_GetNextInterchangeWarning function only returns those interchangeability warnings that are generated after calling this function, you must clear the list of interchangeability warnings by repeatedly calling the niSwitch_GetNextInterchangeWarning function until no interchangeability warnings are returned. If you are not interested in the content of those warnings, you can call the niSwitch_ClearInterchangeWarnings function.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.

Related Information

  • niSwitch_ClearInterchangeWarnings
  • niSwitch_GetNextInterchangeWarning

niSwitch_GetError

Specific Function

C Function Prototype

ViStatus niSwitch_GetError (ViSession vi, ViStatus* code, 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 you specify a valid IVI session for the vi parameter, this function retrieves and then clears the error information for the session. If the user passes VI_NULL for the vi parameter, this function retrieves and then 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. Normally, the error information describes the first error that occurred since the user last called niSwitch_GetError or niSwitch_ClearError.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
code ViStatus Returns the error code for the session or execution thread.
If you pass 0 for bufferSize, you can pass VI_NULL for this parameter.
buffersize ViInt32 Pass 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 bufferSize–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 bufferSize 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.
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 bufferSize parameter. If the error description, including the terminating NULL byte, contains more bytes than you indicate with the bufferSize, the function copies bufferSize–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 bufferSize 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.

Related Information

  • Error and Status Codes

niSwitch_ClearError

Specific Function

C Function Prototype

ViStatus niSwitch_ClearError (ViSession vi);

Purpose

This function clears the error code and error description for the IVI session. If you specify a valid IVI session for the vi 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 vi 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 deallocates 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 niSwitch_GetError function, which occurs when a call to niSwitch_init or niSwitch_InitWithOptions fails.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.

Related Information

  • Error and Status Codes

niSwitch_LockSession

Specific Function

C Function Prototype

ViStatus niSwitch_LockSession (ViSession vi, ViBoolean* 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:

  • Your application called niSwitch_LockSession.
  • A call to the instrument driver locked the session.
  • A call to the IVI engine locked the session.

After your call to niSwitch_LockSession returns successfully, no other threads can access the instrument session until you call niSwitch_UnlockSession. Use niSwitch_LockSession and niSwitch_UnlockSession around a sequence of calls to NI-SWITCH functions if you require that the instrument retain its settings through the end of the sequence. You can safely make nested calls to niSwitch_LockSession within the same thread. To completely unlock the session, balance each call to niSwitch_LockSession with a call to niSwitch_UnlockSession. If, however, you use the callerHasLock parameter in all calls to niSwitch_LockSession and niSwitch_UnlockSession within a function, the IVI Library locks the session only once within the function regardless of the number of calls you make to niSwitch_LockSession. This allows you to call niSwitch_UnlockSession just once at the end of the function.

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
callerHasLock 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. 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 niSwitch_LockSession or niSwitch_UnlockSession in the same function. The parameter is an input/output parameter. niSwitch_LockSession and niSwitch_UnlockSession each inspect the current value and take the following actions:

- If the value is VI_TRUE, niSwitch_LockSession does not lock the session again. If the value is VI_FALSE, niSwitch_LockSession obtains the lock and sets the value of the parameter to VI_TRUE.

- If the value is VI_FALSE, niSwitch_UnlockSession does not attempt to unlock the session. If the value is VI_TRUE, niSwitch_UnlockSession releases the lock and sets the value of the parameter to VI_FALSE.
Thus, you can, call niSwitch_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( niSwitch_LockSession(vi, &haveLock));
viCheckErr( TakeAction1(vi));
if (flags & BIT_2)
{
viCheckErr( niSwitch_UnlockSession(vi, &haveLock));
viCheckErr( TakeAction2(vi));
viCheckErr( niSwitch_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. */

niSwitch_UnlockSession(vi, &haveLock);
return error;
}

Related Information

  • niSwitch_UnlockSession

niSwitch_UnlockSession

Specific Function

C Function Prototype

ViStatus niSwitch_UnlockSession (ViSession vi, ViBoolean* callerHasLock);

Purpose

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

Parameters

Name Type Description
vi ViSession A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
callerHasLock 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. 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 niSwitch_LockSession or niSwitch_UnlockSession in the same function. The parameter is an input/output parameter. niSwitch_LockSession and niSwitch_UnlockSession each inspect the current value and take the following actions:
- If the value is VI_TRUE, niSwitch_LockSession does not lock the session again. If the value is VI_FALSE, niSwitch_LockSession obtains the lock and sets the value of the parameter to VI_TRUE.
- If the value is VI_FALSE, niSwitch_UnlockSession does not attempt to unlock the session. If the value is VI_TRUE, niSwitch_UnlockSession releases the lock and sets the value of the parameter to VI_FALSE.

Thus, you can, call niSwitch_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( niSwitch_LockSession(vi, &haveLock));
viCheckErr( TakeAction1(vi)); if (flags & BIT_2)
{
viCheckErr( niSwitch_UnlockSession(vi, &haveLock));
viCheckErr( TakeAction2(vi));
viCheckErr( niSwitch_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. */
niSwitch_UnlockSession(vi, &haveLock);
return error;
}

Related Information

  • niSwitch_LockSession

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-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