QUICK REFERENCE GUIDE
TM
National Instruments
Switch Executive
This document contains quick reference information about examples, VIs/functions,
route specification strings, and error codes for NI Switch Executive (NISE).
Examples
ICON
VI/FUNCTION NAME AND DESCRIPTION
Getting Started
Opens a session and makes a route connection.
Interactive Control
Uses many of the API functions through an interactive tool.
Route Specification Syntax Example
Demonstrates the many different aspects of route specifications, including
usage of routes, route groups, fully specified routes, and combinations of
route types.
Sequenced Connect And Disconnect
Uses Connect and Disconnect to sequence through different switching
system states.
Using Find Route to Connect Two Channels
Uses Find Route to determine a path between two channels and then
connects the path.
ICON
TYPE
PARAMETER
VALUE TO SET, COMMENTS
niSE Connect And Disconnect (continued)
NISEInt32
multiconnectMode • USE_DEFAULT_MODE (–1)
• NO_MULTICONNECT (0)
• MULTICONNECT_ROUTES (1)
NISEInt32
operationOrder
• BREAK_BEFORE_MAKE (1)
• BREAK_AFTER_MAKE (2)
NISEBoolean
waitForDebounce
• NISE_TRUE
• NISE_FALSE
niSE Disconnect
(niSE_Disconnect)
Disconnects the routes specified in the disconnection specification.
NISESession
sessionHandle
disconnectSpec
Reference to virtual device session
NISEConstString
String describing the
disconnections to be made
niSE Disconnect All
(niSE_DisconnectAll)
Disconnects all connections on every IVI switch device managed by the
NISE session reference passed to this function.
NISESession
sessionHandle
Reference to virtual device session
niSE Find Route
(niSE_FindRoute)
Finds an existing or potential route between channel 1 and channel 2.
NISESession
sessionHandle
channel 1
Reference to virtual device session
NISEConstString
Channel name of one of the end
points of the route to find
NISEConstString
NISEBuffer* [out]
channel 2
routeSpec
Channel name of one of the end
points of the route to find
Returns the path between the
channels if PATH_EXISTS or
PATH_AVAILABLE
NISEInt32 * [in/out] routeSpecSize
• Input = size of the route string
buffer being passed
• Return = the size required to hold
the entire route string
NISEInt32 * [out]
routeCapability
• PATH_AVAILABLE (1)
• PATH_EXISTS (2)
• PATH_UNSUPPORTED (3)
• RSRC_IN_USE (4)
• SOURCE_CONFLICT (5)
• CHANNEL_NOT_AVAILABLE (6)
• CHANNELS_HARDWIRED (7)
Functions continued on the next page
© National Instruments Corporation
3
NI Switch Executive Quick Reference Guide
Functions (continued)
ICON
TYPE
PARAMETER
VALUE TO SET, COMMENTS
niSE Is Debounced
(niSE_IsDebounced)
Checks to see if the switching system is debounced or not.This VI/function
does not wait for debouncing to occur and returns true if the system is fully
debounced.
NISESession
sessionHandle
Reference to virtual device session
NISEBoolean* [out] isDebounced
• NISE_TRUE
• NISE_FALSE
niSE Wait For Debounce
(niSE_WaitForDebounce)
Waits for all of the switches in the NISE virtual device to debounce.
NISESession
NISEInt32
sessionHandle
maxTime
Reference to virtual device session
Amount of time to wait (in ms) for
the debounce to complete before
timing out
Additional C/C++/Visual Basic Functions
C, C++, and Visual Basic users have two additional functions available that are not
needed in LabVIEW.
TYPE
PARAMETER
VALUE TO SET, COMMENTS
niSE_ClearError
Clears the last queried error from memory.
NISESession
sessionHandle
Reference to virtual device session
niSE_GetError
Queries for and returns the most recent error.
NISESession
sessionHandle
errorNumber
Reference to virtual device session
NISEStatus* [out]
Returns the error number of the first
error that occurred in the session since
the error was last cleared
NISEBuffer* [out]
NISEInt32* [out]
errorDescription
Returns a string describing the error
errorDescriptionSize
• Input = size of the error description
buffer being passed
• Return = size required to hold entire
string
4
ni.com
NI Switch Executive Quick Reference Guide
Route Specification Strings
Route specification strings are the paths connecting two channels and are composed of
one or more routes delimited by ampersands (&). For example, in the following line of
syntax, there are three defined routes or route groups:
routeOrGroup & routeOrGroup & routeOrGroup...
where routeOrGroupcan be:
•
•
•
Route name
Route group name
Two endpoint channels to be connected that are delimited by ->. NISE dynamically
determines the path between the endpoints. In this mode, a hardwire alias name may
be substituted for the endpoints.
channel -> channel
•
Fully specified path enclosed in square brackets consisting of one or more endpoint
channels delimited by ->:
[channel -> channel -> channel...]
where channelcan be:
•
•
A channel alias name
A unique name created by combining the IVI device logical name and IVI
channel name separated by a forward slash (/) delimiter. For example,
(device/iviChan).
Note
•
Any channel, other than an endpoint, within a route specification
string must be reserved for routing or directly hardwired to one of
the endpoint channels.
• Channelsused as endpoints must not be reserved for routing
channels.
•
When connecting a route, the list of channels must obey the
exclusion rules by both explicitly in the route specification string, as
well as implicitly by any previous connections. Exclusion violations
result in an error.
The following are samples of route specification strings for a matrix:
• [SampleMatrix1/c0->SampleMatrix1/r1->SampleMatrix1/c4]
• [Scope->R3->SampleMatrix1/c6]
• ArbToInput & ScopeToOutput
• PowerDevice & [Scope->R3->UUT_Out]
• DCPower->UUT_Vcc
Each supported ADE has an associated Route Specification String Example. Refer to the
examples for the appropriate ADE to see how route specification strings are used when
programming.
© National Instruments Corporation
5
NI Switch Executive Quick Reference Guide
Error Codes
VALUE
(HEX)
VALUE
(DECIMAL) DESCRIPTION
INTERNAL
FFFF8EB8
–29000
An internal error has occurred. Please contact National Instruments
technical support.
IVI_DRIVER_NO_SIMULATION
FFFF8EB7 –29001 The IVI-specific driver does not support simulation mode.
INVALID_VIRTUAL_DEVICE_NAME
FFFF8EB6
–29002
The specified NI Switch Executive virtual device is invalid or does not
exist.
INVALID_SESSION
FFFF8EB5 –29003
This session is not a valid NI Switch Executive virtual device session.
INSUFFICIENT_SYSTEM_RESOURCES
FFFF8EB4
–29004
NI Switch Executive requires system resources that are currently
unavailable. Close other applications and try again.
AMBIGUOUS_NAME
FFFF8EB3 –29005
The specified name is ambiguous. Specify a unique name.
INVALID_IVI_LOGICAL_NAME
FFFF8EB2 –29006 The IVI logical name is invalid or the device does not exist.
INVALID_ROUTE_SPECIFICATION
FFFF8EB1
–29007
The route specification string contains invalid characters or could not
be understood.
EVAL_TIMED_OUT
FFFF8EAF –29008
NI Switch Executive is running with an evaluation license and the time
limit for this session has expired. Restart your application to continue
evaluating.
INVALID_NAME
FFFF8EAE –29009
The name contains invalid characters.
RUNTIME_IMPORTING_EVAL
FFFF8EAD –29010
This configuration was created with an evaluation license. Deployment
licenses can only import configurations created with a development
license. Import the configuration into a development license system and
re-export the file to resolve the problem.
EVAL_EXPIRED_IMPORTING
FFFF8EAC –29011
NI Switch Executive cannot import configurations once the evaluation
period has expired.
RUNTIME_EXPORTING
FFFF8EAB –29012
NI Switch Executive deployment licenses cannot export configurations.
The operation requested requires a development license.
IMPORTING_FILE_ACCESS
FFFF8EAA –29013
There was an error when accessing (open or read) the NI Switch
Executive configuration file.
6
ni.com
NI Switch Executive Quick Reference Guide
VALUE
(HEX)
VALUE
(DECIMAL) DESCRIPTION
IMPORTING_FILE_FORMAT
FFFF8EA9 –29014
The file is not a valid NI Switch Executive configuration file.
The endpoints of the path do not match the existing endpoints.
Cannot connect this path on the device.
INVALID_END_POINTS
FFFF8EA8 –29015
INVALID_PATH
FFFF8EA7 –29016
INVALID_CHANNEL_SPECIFICATION
FFFF8EA6
–29017
The channel specification string contains invalid characters or could not
be understood.
DLL_NOT_FOUND
FFFF8EA5
–29018
A needed DLL was not found. Check to ensure that NI Switch
Executive is properly installed and that all needed DLLs are in the
search path.
FUNCTION_NOT_FOUND
FFFF8EA4
–29019
A needed function in a DLL could not be found. Although the DLL exists,
it may be an incorrect version and may not contain the needed function.
MAX_TIME_EXCEEDED
FFFF8EA3 –29020
One or more switching devices have not debounced within the specified
maximum time.
ROUTE_ALREADY_EXISTS
FFFF8EA2 –29021
The route you are trying to connect or a route with the same endpoints
is already connected.
ROUTE_EXISTS_AS_UNSHAREABLE
FFFF8EA1
–29022
The route you are trying to connect already exists as a non-multiconnect
route. It must be disconnected before you can make a multiconnect
route.
ROUTE_EXISTS_BY_DIFFERENT_PATH
FFFF8EA0
–29023
The route you are trying to connect already exists but is connected
through a different path than the one specified.
ROUTE_DOES_NOT_EXIST
FFFF8E9F –29024
The specified route does not exist.You cannot disconnect a route that
does not exist.
PARTIAL_DISCONNECT
FFFF8E9E –29025
Device specific errors occurred during the disconnect operation.
RESOURCE_IN_USE
–29026
A connection could not be made because one of the switch resources
needed to make the connection is used as part of another
currently connected route.
FILE_WRITE
FFFF8E9D
–29027
An error occurred while attempting to write to file.
Error Codes continued on the next page
© National Instruments Corporation
7
NI Switch Executive Quick Reference Guide
Error Codes (continued)
VALUE
(HEX)
VALUE
(DECIMAL) DESCRIPTION
FILE_READ
FFFF8E9C
–29028
An error occurred while attempting to read from file.
INVALID_MULTICONNECT_MODE
FFFF8E9B –29029 Invalid multiconnect mode.
INVALID_OPERATION_ORDER
FFFF8E9A –29030 Invalid operation order.
CONFIG_CHANNEL_CONFLICT
FFFF8E99
–29031
A reserved for routing channel required for connecting this route is
already in use by another route.
SOURCE_CHANNEL_CONFLICT
FFFF8E98
–29032
Connecting this route would cause excluded channels to be shorted
together.
ROUTE_EXISTS_WITH_DIFFERENT_MODE
FFFF8E97
–29033
The route you are trying to connect already exists with a different
multiconnect mode. It must be disconnected before you can make this
connection.
DISABLED_CHANNEL
FFFF8E96 –29034
The channel you are trying to use has been disabled for this virtual
device.
CANNOT_CONNECT_TO_ITSELF
FFFF8E95
–29035
You cannot connect a channel to itself. Either your endpoint channels are
the same or they reside on the same hardwire.
ROUTE_NOT_FOUND
FFFF8E94 –29036
Route cannot be found between the specified endpoints.
Programming Flow
The following diagram shows a typical programming flow for NI Switch Executive.
Switch Control Functions
Miscellaneous Functions
TM
TM
TM
TM
TM
TM
TM
CVI , IVI ,LabVIEW , National Instruments , NI , ni.com , and TestStand are trademarks of
National Instruments Corporation. Product and company names mentioned herein are trademarks or
trade names of their respective companies. For patents covering National Instruments products,
refer to the appropriate location: Help»Patents in your software, the patents.txtfile on your CD,
or ni.com/patents.
© 2001–2004 National Instruments Corporation.
All rights reserved. Printed in Ireland.
*371308A-01*
371308A-01
Jul04
|