IviSwtch_SetPath

IviSwtchBase Capability Group

C Function Prototype

ViStatus IviSwtch_SetPath (ViSession vi, ViConstString pathList);

Purpose

This function connects two channels by establishing the exact path you specify with the pathList parameter. This function allows you to bypass the automatic routing feature provided by the IviSwtch driver, and gives you deterministic control over the path that is created between two channels. You can specify the exact path, in terms of configuration channels, used to connect two channels. The first and last entries in the pathList represent the two channels you wish to connect.

The driver makes a connection between the channels using the configuration channels. These intermediary steps are called legs of the path. The format of the leg of the path is ch1->conf1, where ch1 and conf1 are the two channels the driver used to establish the connection between the first and the last channel. The path list syntax is a comma-separated list of path legs that obey the following rules:

• The second channel of a leg in the path list must be the same as the first channel in the subsequent leg.
• Every channel in the path list other than the first and the last must be a configuration channel.

An example of a path list is: ch1->conf1,conf1->ch2

This string is not interchangeable because the names of switches within the switch module are not required to be interchangeable and depend on the internal architecture of the switch module. However, you can use the IviSwtch_Connect and then IviSwtch_GetPath functions to retrieve an already existing path. This allows you to guarantee that the routing can be recreated exactly.

If the instrument cannot parse the input path list string, this function returns the IVISWTCH_ERROR_INVALID_SWITCH_PATH error without performing any connection operation.

If the specified path list string is empty, this function returns IVISWTCH_ERROR_EMPTY_SWITCH_PATH without performing any connection operation.

If one of the channels in the path list is a configuration channel that is currently in use, this function returns IVISWTCH_ERROR_RSRC_IN_USE without performing any connection operation.

If an explicit connection is made to a configuration channel, this function returns IVISWTCH_ERROR_IS_CONFIGURATION_CHANNEL without performing any connection operation.

If one of the non-terminal channels in the path list is not a configuration channel, this function returns IVISWTCH_ERROR_NOT_A_CONFIGURATION_CHANNEL without performing any connection operation.

If the path list attempts to connect between two different source channels, this function returns IVISWTCH_ERROR_ATTEMPT_TO_CONNECT_SOURCES without performing any connection operation.

If the path list attempts to connect between channels that already have an explicit connection, this function returns IVISWTCH_ERROR_EXPLICIT_CONNECTION_EXISTS without performing any connection operation.

If a leg in the path list does not begin with a channel name, this function returns IVISWTCH_ERROR_LEG_MISSING_FIRST_CHANNEL without performing any connection operation.

If a leg in the path list is missing the second channel, this function returns IVISWTCH_ERROR_LEG_MISSING_SECOND_CHANNEL without performing any connection operation.

If the first and the second channels in the leg are the same, this function returns IVISWTCH_ERROR_CHANNEL_DUPLICATED_IN_LEG without performing any connection operation.

If a channel name is duplicated in the path string, this function returns IVISWTCH_ERROR_CHANNEL_DUPLICATED_IN_PATH without performing any connection operation.

If the first channel of a leg in the path is not the same as the second channel in the previous leg, this function returns IVISWTCH_ERROR_DISCONTINUOUS_PATH without performing any connection operation.

If the path list contains a leg with two channels that cannot be directly connected, this function returns IVISWTCH_ERROR_CANNOT_CONNECT_DIRECTLY without performing any connection operation.

If a leg in the path contains two channels that are already directly connected, this function returns IVISWTCH_ERROR_CHANNELS_ALREADY_CONNECTED without performing any connection operation.

This function applies default values to attributes that you have not set. For more information on default values, consult default values.

Note  This function performs interchangeability checking when the IVISWTCH_ATTR_INTERCHANGE_CHECK attribute is set to VI_TRUE. Use NI Spy to view interchangeability warnings. Alternately, you may use the IviSwtch_GetNextInterchangeWarning function to retrieve interchangeability warnings. For more information about interchangeability checking, consult interchangeability.

Parameters

Name	Type	Description
vi	ViSession	The instrument handle that you obtain from the IviSwtch_init or IviSwtch_InitWithOptions functions. The handle identifies a particular IVI session.
pathList	ViConstString	Pass the path list for the path you previously created that you want the switch module to establish. You can obtain the path list for a path you previously created with the IviSwtch_GetPath function. Example: The path from Ch1 to Ch3 over Conf1 is: "Ch1->Conf1,Conf1->Ch3"

Return Values