niSE_FindRoute

Download PDF

Updated2023-02-21
3 minute(s) read

Finds an existing or potential route between channel 1 and channel 2.

Function Prototype

Function niSE_FindRoute(	sessionHandle As NISESession,
	channel1 As String,
	channel2 As String,
	routeSpec As String,
	routeSpecSize As Long,
	routeCapability As NISERouteCapability) As NISEStatus

Parameters

Input

Name	Type	Description
sessionHandle	NISESession	The session referencing this NI Switch Executive virtual device session.
channel1	String	The channel name of one of the endpoints of the route to find. The channel name must either be a channel alias name or a name in the device/ivichannel syntax. Examples: MyChannel Switch1/R0
channel2	String	The channel name of one of the endpoints of the route to find. The channel name must either be a channel alias name or a name in the device/ivichannel syntax. Examples: MyChannel Switch1/R0

Input/Output

Name	Type	Description
routeSpecSize	Long	The routeSpecSize is a Long that is passed by reference into the function. As an input, it is the size of the route string buffer being passed. If the route string is larger than the string buffer being passed, only the portion of the route string that can fit in the string buffer is copied into it. On return from the function, routeSpecSize holds the size required to hold the entire route string. This size may be larger than the buffer size as the function always returns the size needed to hold the entire buffer. You can pass NULL for this parameter if you are not interested in the return value for routeSpecSize and routeSpec.

Output

Name	Type	Description
routeSpec	String	The fully specified route path surrounded by delimiting square brackets—if the route exists or is possible. Refer to Route Specification Strings for more information.
routeCapability	NISERouteCapability	The return value which expresses the capability of finding a valid route between Channel 1 and Channel 2. Refer to the Path Capability table for value descriptions.

niSE_FindRoute Details

The returned route specification contains the route specification, and the route capability indicates whether the route existed, is possible, or is not possible for various reasons.

The route specification string returned from niSE_FindRoute can be passed to other NI Switch Executive API functions, such as niSE_Connect, niSE_Disconnect, and niSE_ConnectAndDisconnect, that use route specification strings.

To dynamically allocate space for the routeSpec buffer, call niSE_FindRoute twice. The first call should specify a routeSpecSize of 0 and then use the returned routeSpecSize to allocate the correct buffer size.

Path Capability

Path capability may be any one of the following:

Value	Name	Description
1	NISE_VAL_PATH_AVAILABLE	A path between channel 1 and channel 2 is available. The route specification parameter returns a string describing the available path.
2	NISE_VAL_PATH_EXISTS	A path between channel 1 and channel 2 already exists. The route specification parameter returns a string describing the existing path.
3	NISE_VAL_PATH_UNSUPPORTED	There is no potential path between channel 1 and channel 2 given the current configuration.
4	NISE_VAL_RSRC_IN_USE	There is a potential path between channel 1 and channel 2, although a resource needed to complete the path is already in use.
5	NISE_VAL_EXCLUSION_CONFLICT	Channel 1 and channel 2 cannot be connected because their connection would result in an exclusion violation.
6	NISE_VAL_CHANNEL_NOT_AVAILABLE	One of the channels is not useable as an endpoint channel. Make sure that it is not marked as a configuration channel.

NI Switch Executive

Table of Contents