IviSwtch_Connect

IviSwtchBase Capability Group

C Function Prototype

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

Purpose

You can connect two channels using this function. The driver calculates the shortest path between the two channels you specified. If a path is not available, the function returns one of the following errors:

• IVISWTCH_ERROR_EXPLICIT_CONNECTION_EXISTS, if the two channels are already explicitly connected by calling either the IviSwtch_Connect or IviSwtch_SetPath function. If the path already exists, the operation does not count the number of calls. For example, it does not remember that there were two calls to connect, thus requiring two calls to disconnect, but instead returns this error.
• IVISWTCH_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.
• IVISWTCH_ERROR_ATTEMPT_TO_CONNECT_SOURCES, if both channels are connected to a different source. Error elaboration contains information about sources to which channel 1 and 2 connect.
• IVISWTCH_ERROR_CANNOT_CONNECT_TO_ITSELF, if channels 1 and 2 are one and the same channel.
• IVISWTCH_ERROR_PATH_NOT_FOUND, if the driver cannot find a path between the two channels.

This function returns as soon as the command is given to the switch module and the switch module is ready for another command. This may be before or after the switches involved settle. Use the IviSwtch_IsDebounced function to determine if the switch module has settled. Use the IviSwtch_WaitForDebounce function if you want to block program execution until all switches involved in the path creation have settled.

The IVI spec does not specify the default names for the channels because this depends on the architecture of the switch module. You can specify aliases for the vendor-defined channel names in the IVI configuration file.

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

Notes   The paths are bi-directional. For example, if a path exists from channel CH1 to CH2, then a path from channel CH2 to CH1 also exists. 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. about interchangeability checking, refer to 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.
channel1	ViConstString	You identify a path with two channels. Pass one of the virtual channel names for which you want to create a path. Pass the other channel name as the channel2 parameter. Virtual channel names are aliases for instrument specific channel strings. The instrument specific channel strings can differ from one instrument to another. Virtual channel names allow you to use and swap instruments without having to change the channel names in your source code. You assign a virtual channel name to an instrument specific channel through MAX. This control accepts virtual channel names you have assigned to the specific instrument you are using. This control also accepts the instrument specific channel names. Note  You can specify the channel name as a string variable or as a literal enclosed in double quotes.
channel2	ViConstString	You identify a path with two channels. Pass one of the virtual channel names for which you want to create a path. Pass the other channel name as the channel1 parameter. Virtual channel names are aliases for instrument specific channel strings. The instrument specific channel strings can differ from one instrument to another. Virtual channel names allow you to use and swap instruments without having to change the channel names in your source code. You assign a virtual channel name to an instrument specific channel through MAX. This control accepts virtual channel names you have assigned to the specific instrument you are using. This control also accepts the instrument specific channel names. Note  You can specify the channel name as a string variable or as a literal enclosed in double quotes.

Return Values