Skip to content

NI SWITCH Route Functions

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

Route Functions

niSwitch_Connect

IviSwtchBase Capability Group

C Function Prototype

ViStatus niSwitch_Connect (ViSession vi, ViConstString channel1, ViConstString channel2);

Purpose

Creates a path between channel1 and channel2. NI-SWITCH calculates and uses the shortest path between the two channels. Refer to Immediate Operations) for information about channel usage types.

If a path is not available, the function returns one of the following errors:

  • NISWITCH_ERROR_EXPLICIT_CONNECTION_EXISTS, if the two channels are already connected by calling either the niSwitch_Connect or niSwitch_SetPath function.
  • NISWITCH_ERROR_IS_CONFIGURATION_CHANNEL, if a channel is a configuration channel. Error elaboration contains information about which of the two channels is a configuration channel.
  • NISWITCH_ERROR_ATTEMPT_TO_CONNECT_SOURCES, if both channels are connected to a different source. Error elaboration contains information about sources channel1 and channel2 connect to.
  • NISWITCH_ERROR_CANNOT_CONNECT_TO_ITSELF, if channel1 and channel2 are one and the same channel.
  • NISWITCH_ERROR_PATH_NOT_FOUND, if the driver cannot find a path between the two channels.
Note  Paths are bidirectional. For example, if a path exists between channels CH1 and CH2, then the path also exists between channels CH2 and CH1.

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.
channel1 ViConstString Input one of the channel names of the desired path. Pass the other channel name as channel2. Refer to Devices) for valid channel names for the switch module.

Examples of valid channel names:

ch0, com0, ab0, r1, c2, cjtemp
channel2 ViConstString Input one of the channel names of the desired path. Pass the other channel name as channel1. Refer to Devices) for valid channel names for the switch module.

Examples of valid channel names:

ch0, com0, ab0, r1, c2, cjtemp

Related Information

  • Immediate Operations
  • niSwitch_ConnectMultiple
  • niSwitch_CanConnect
  • niSwitch_SetPath

niSwitch_ConnectMultiple

C Function Prototype

ViStatus niSwitch_ConnectMultiple (ViSession vi, ViConstString connectionList);

Purpose

Creates the connections between channels specified in connection list. Specify connections with two endpoints only or the explicit path between two endpoints. NI-SWITCH calculates and uses the shortest path between the channels. Refer to Setting Source and Configuration Channels) for information about channel usage types. In the event of an error, connecting stops at the point in the list where the error occurred.

If a path is not available, the function returns one of the following errors:

  • NISWITCH_ERROR_EXPLICIT_CONNECTION_EXISTS, if the two channels are already connected.
  • NISWITCH_ERROR_IS_CONFIGURATION_CHANNEL, if a channel is a configuration channel. Error elaboration contains information about which of the two channels is a configuration channel.
  • NISWITCH_ERROR_ATTEMPT_TO_CONNECT_SOURCES, if the connection between two channels is connected to different source channels. Error elaboration contains information about the connection channel with errors.
  • NISWITCH_ERROR_CANNOT_CONNECT_TO_ITSELF, if two channels in a single connection are the same channel.
  • NISWITCH_ERROR_PATH_NOT_FOUND, if the driver cannot find a path between two channels.
!Note Note  Paths are bidirectional. For example, if a path exists between channels ch1 and ch2, then the path also exists between channels ch2 and ch1.

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.
connectionList ViConstString Connection list specifies a list of connections between channels to make. NI-SWITCH validates the connection list, and aborts execution of the list if errors are returned. Refer to Connection and Disconnection List Syntax) for valid connection list syntax and examples. Refer to Devices) for valid channel names for the switch module.

Related Information

  • Immediate Operations
  • niSwitch_Connect

niSwitch_Disconnect

IviSwtchBase Capability Group

C Function Prototype

ViStatus niSwitch_Disconnect (ViSession vi, ViConstString channel1, ViConstString channel2);

Purpose

Destroys the path between two channels that you create with the niSwitch_Connect or niSwitch_SetPath function.

If a path is not available, the function returns one of the following errors:

  • NISWITCH_ERROR_NO_SUCH_PATH, if a path does not exist between two 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.
channel1 ViConstString Input one of the channel names of the path to break. Pass the other channel name as channel2. Refer to Devices) for valid channel names for the switch module.

Examples of valid channel names:

ch0, com0, ab0, r1, c2, cjtemp
channel2 ViConstString Input one of the channel names of the path to break. Pass the other channel name as channel1. Refer to Devices) for valid channel names for the switch module.

Examples of valid channel names:

ch0, com0, ab0, r1, c2, cjtemp

Related Information

  • Immediate Operations
  • niSwitch_DisconnectMultiple

niSwitch_DisconnectAll

IviSwtchBase Capability Group

C Function Prototype

ViStatus niSwitch_DisconnectAll (ViSession vi);

Purpose

Breaks all existing paths.

If the switch module cannot break all paths, the NISWITCH_WARN_PATH_REMAINS warning is returned.

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

  • Immediate Operations
  • niSwitch_Disconnect

niSwitch_DisconnectMultiple

C Function Prototype

ViStatus niSwitch_DisconnectMultiple (ViSession vi, ViConstString disconnectionList);

Purpose

Breaks the connections between channels specified in disconnection list. If no connections exist between channels, NI-SWITCH returns an error. In the event of an error, the VI stops at the point in the list where the error occurred.

If a path is not available, the function returns the following error:

  • NISWITCH_ERROR_NO_SUCH_PATH, if a path does not exist between two 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.
disconnectionList ViConstString Disconnection list specifies a list of connections between channels to break. NI-SWITCH validates the disconnection list, and aborts execution of the list if errors are returned. Refer to Connection and Disconnection list Syntax) for valid connection list syntax and examples. Refer to Devices) for valid channel names for the switch module.

Related Information

  • Immediate Operations
  • niSwitch_Disconnect

niSwitch_IsDebounced

IviSwtchBase Capability Group

C Function Prototype

ViStatus niSwitch_IsDebounced (ViSession vi, ViBoolean* isDebounced);

Purpose

Indicates if all created paths have settled by returning the value of the NISWITCH_ATTR_IS_DEBOUNCED attribute.

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.
isDebounced ViBoolean VI_TRUE indicates that all created paths have settled. VI_FALSE indicates that all created paths have not settled.

Related Information

  • Electromechanical Relays
  • niSwitch_WaitForDebounce

niSwitch_WaitForDebounce

IviSwtchBase Capability Group

C Function Prototype

ViStatus niSwitch_WaitForDebounce (ViSession vi, ViInt32 maximumTime_ms);

Purpose

Pauses until all created paths have settled.

If the time you specify with the maximumTime_ms parameter elapses before the switch paths settle, this function returns the NISWITCH_ERROR_MAX_TIME_EXCEEDED error.

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.
maximumTime_ms ViInt32 Specifies the maximum length of time to wait for all relays in the switch module to activate or deactivate. If the specified time elapses before all relays activate or deactivate, a timeout error is returned. The default value is5000 ms.

Related Information

  • niSwitch_IsDebounced
  • Electromechanical Relays

niSwitch_CanConnect

IviSwtchBase Capability Group

C Function Prototype

ViStatus niSwitch_CanConnect (ViSession vi, ViConstString channel1, ViConstString channel2, ViInt32* pathCapability);

Purpose

Verifies that a path between channel1 and channel2 can be created.

If a path is possible in the switch module, the availability of that path is returned given the existing connections. If the path is possible but in use, a NISWITCH_WARN_IMPLICIT_CONNECTION_EXISTS warning is returned.

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.
channel1 ViConstString

Input one of the channel names of the desired path. Pass the other channel name as the channel2. Refer to Devices) for valid channel names for the switch module.

Examples of valid channel names:

ch0, com0, ab0, r1, c2, cjtemp

The default value is an empty string.

channel2 ViConstString

Input one of the channel names of the desired path. Pass the other channel name as channel1. Refer to Devices) for valid channel names for the switch module.

Examples of valid channel names:

ch0, com0, ab0, r1, c2, cjtemp

The default value is an empty string.

pathCapability ViInt32

Indicates whether a path is valid.

Possible values include:

Value Description
NISWITCH_VAL_PATH_AVAILABLE Indicates that NI-SWITCH can create the path at this time.
NISWITCH_VAL_PATH_EXISTS Indicates that the path already exists.
NISWITCH_VAL_PATH_UNSUPPORTED Indicates that the instrument is not capable of creating a path between the channels you specify.
NISWITCH_VAL_RSRC_IN_USE Indicates that although the path is valid, NI-SWITCH cannot create the path at this moment because the switch is currently using one or more of the required channels to create another path. You must destroy the other path before creating this one.
NISWITCH_VAL_SOURCE_CONFLICT Indicates that the instrument cannot create a path because both channels are connected to different source channels.
NISWITCH_VAL_CHANNEL_NOT_AVAILABLE Indicates that NI-SWITCH cannot create a path between the two channels because one of the channels is a configuration channel and unavailable for external connections.

Related Information

  • niSwitch_GetPath

niSwitch_SetPath

IviSwtchBase Capability Group

C Function Prototype

ViStatus niSwitch_SetPath (ViSession vi, ViConstString pathList);

Purpose

Connects two channels by specifying an explicit path in pathList. niSwitch_SetPath is particularly useful where path repeatability is important, such as in calibrated signal paths. If this is not necessary, use niSwitch_Connect.

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.
pathList ViConstString A string composed of comma-separated paths between channel 1 and channel 2. The first and last names in the path are the endpoints of the path. Every other channel in the path are configuration channels.

Example of a valid path list string:

ch0->com0, com0->ab0.

In this example, com0 is a configuration channel.



Obtain the path list for a previously created path with niSwitch_GetPath.

Related Information

  • niSwitch_GetPath

niSwitch_GetPath

IviSwtchBase Capability Group

C Function Prototype

ViStatus niSwitch_GetPath (ViSession vi, ViConstString channel1, ViConstString channel2, ViInt32 bufferSize, ViChar[] path);

Purpose

Returns a string that identifies the explicit path created with niSwitch_Connect. Pass this string to niSwitch_SetPath to establish the exact same path in future connections.

In some cases, multiple paths are available between two channels. When you call niSwitch_Connect, NI-SWITCH selects an available path; however, the driver may not always select the same path through the switch module.

niSwitch_GetPath only returns those paths explicitly created by niSwitch_Connect or niSwitch_SetPath. For example, if you connect channels CH1 and CH3, and then channels CH2 and CH3, an explicit path between channels CH1 and CH2 does not exist and an error is returned.

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.
channel1 ViConstString

Input one of the channel names of the desired path. Pass the other channel name as channel2. Refer to Devices) for valid channel names for the switch module.

Examples of valid channel names:

ch0, com0, ab0, r1, c2, cjtemp

The default value is an empty string.

channel2 ViConstString

Input one of the channel names of the desired path. Pass the other channel name as channel1. Refer to Devices) for valid channel names for the switch module.

Examples of valid channel names:

ch0, com0, ab0, r1, c2, cjtemp

The default value is an empty string.

bufferSize ViInt32 Pass the number of bytes in the ViChar array you specify for the Path parameter. If the current value of the attribute, including the terminating NULL byte, contains more bytes that 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 "R1->C1" and bufferSize is 4, the function places "R1-" into the buffer and returns 7. If you pass 0, you can pass VI_NULL for path. This enables you to find out the path size and to allocate the buffer of the appropriate size before calling this function again.
path ViChar[] A string composed of comma-separated paths between channel1 and channel2. The first and last names in the path are the endpoints of the path. All other channels in the path are configuration channels.

Examples of returned paths:

ch0->com0, com0->ab0

Related Information

  • niSwitch_SetPath

Table of Contents

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