NI SWITCH Route Functions
- niSwitch_IsDebounced
- niSwitch_Connect
- niSwitch_ConnectMultiple
- niSwitch_GetPath
- niSwitch_DisconnectAll
- niSwitch_SetPath
- niSwitch_CanConnect
- niSwitch_WaitForDebounce
- niSwitch_DisconnectMultiple
- niSwitch_Disconnect
ViStatus niSwitch_Connect (ViSession vi, ViConstString channel1, ViConstString channel2);
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. |
|---|
| 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 |
- Immediate Operations
- niSwitch_ConnectMultiple
- niSwitch_CanConnect
- niSwitch_SetPath
ViStatus niSwitch_ConnectMultiple (ViSession vi, ViConstString connectionList);
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. |
|---|
| 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. |
- Immediate Operations
- niSwitch_Connect
ViStatus niSwitch_Disconnect (ViSession vi, ViConstString channel1, ViConstString channel2);
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.
| 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 |
- Immediate Operations
- niSwitch_DisconnectMultiple
ViStatus niSwitch_DisconnectAll (ViSession vi);
Breaks all existing paths.
If the switch module cannot break all paths, the NISWITCH_WARN_PATH_REMAINS warning is returned.
| 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. |
- Immediate Operations
- niSwitch_Disconnect
ViStatus niSwitch_DisconnectMultiple (ViSession vi, ViConstString disconnectionList);
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.
| 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. |
- Immediate Operations
- niSwitch_Disconnect
ViStatus niSwitch_IsDebounced (ViSession vi, ViBoolean* isDebounced);
Indicates if all created paths have settled by returning the value of the NISWITCH_ATTR_IS_DEBOUNCED attribute.
| 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. |
- Electromechanical Relays
- niSwitch_WaitForDebounce
ViStatus niSwitch_WaitForDebounce (ViSession vi, ViInt32 maximumTime_ms);
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.
| 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. |
- niSwitch_IsDebounced
- Electromechanical Relays
ViStatus niSwitch_CanConnect (ViSession vi, ViConstString channel1, ViConstString channel2, ViInt32* pathCapability);
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.
| 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: 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. |
- niSwitch_GetPath
ViStatus niSwitch_SetPath (ViSession vi, ViConstString pathList);
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.
| 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. |
- niSwitch_GetPath
ViStatus niSwitch_GetPath (ViSession vi, ViConstString channel1, ViConstString channel2, ViInt32 bufferSize, ViChar[] path);
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.
| 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 |
- niSwitch_SetPath