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.
Functions†
ICON TYPE PARAMETER VALUE TO SET, COMMENTS
niSE Open Session
(niSE_OpenSession)
Opens a session to a specified NISE virtual device. Opens communications
with all of the IVI switches associated with the specified NISE virtual device.
Returns a session handle used to identify the virtual device in all subsequent
NISE calls.
NISEConstString virtualDeviceName Name of the NISE virtual device to
NISEConstString options Used to pass information to each of
NISESession* [out] sessionHandle Reference to virtual device session
open a session to
the IVI devices on startup
niSE Close Session
(niSE_CloseSession)
Reduces the reference count of open sessions by one. If the reference count
goes to zero, any open IVI switch sessions are closed.
NISESession sessionHandle Reference to virtual device session
niSE Connect
(niSE_Connect)
Connects the routes specified by the connection specification.
When connecting, it may allow for multiconnection based on the
multiconnection mode.
NISESession sessionHandle Reference to virtual device session
NISEConstString connectSpec String describing the connections
NISEInt32 multiconnectMode • USE_DEFAULT_MODE (–1)
NISEBoolean waitForDebounce • NISE_TRUE
to be made
• NO_MULTICONNECT (0)
• MULTICONNECT_ROUTES (1)
• NISE_FALSE
niSE Connect And Disconnect
(niSE_ConnectAndDisconnect)
Connects the routes specified by the connection specification.
When connecting, it may allow for multiconnection based on the
multiconnection mode. Disconnects the routes specified in the
disconnection specification. This VI/ function is useful for switching
from one state to another state.
NISESession sessionHandle Reference to virtual device session
NISEConstString connectSpec String describing the connections
NISEConstString disconnectSpec String describing the
† Function names for C, C++, LabWindowsTM/CVITM, and Visual Basic are in parentheses.
to be made
disconnections to be made
NI Switch Executive Quick Reference Guide
2 ni.com
ICON TYPE PARAMETER VALUE TO SET, COMMENTS
niSE Connect And Disconnect (continued)
NISEInt32 multiconnectMode • USE_DEFAULT_MODE (–1)
NISEInt32 operationOrder • BREAK_BEFORE_MAKE (1)
NISEBoolean waitForDebounce • NISE_TRUE
• NO_MULTICONNECT (0)
• MULTICONNECT_ROUTES (1)
• BREAK_AFTER_MAKE (2)
• NISE_FALSE
niSE Disconnect
(niSE_Disconnect)
Disconnects the routes specified in the disconnection specification.
NISESession sessionHandle Reference to virtual device session
NISEConstString disconnectSpec 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 Reference to virtual device session
NISEConstString channel 1 Channel name of one of the end
NISEConstString channel 2 Channel name of one of the end
NISEBuffer* [out] routeSpec Returns the path between the
NISEInt32 * [in/out] routeSpecSize • Input = size of the route string
NISEInt32 * [out] routeCapability • PATH_AVAILABLE (1)
points of the route to find
points of the route to find
channels if PATH_EXISTS or
PATH_AVAILABLE
buffer being passed
• Return = the size required to hold
the entire route string
• PATH_EXISTS (2)
• PATH_UNSUPPORTED (3)
• RSRC_IN_USE (4)
• SOURCE_CONFLICT (5)
• CHANNEL_NOT_AVAILABLE (6)
• CHANNELS_HARDWIRED (7)
©
National Instruments Corporation
Functions
continued on the next page
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 sessionHandle Reference to virtual device session
NISEInt32 maxTime 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 Reference to virtual device session
NISEStatus* [out] errorNumber Returns the error number of the first
NISEBuffer* [out] errorDescription Returns a string describing the error
NISEInt32* [out] errorDescriptionSize • Input = size of the error description
NI Switch Executive Quick Reference Guide
error that occurred in the session since
the error was last cleared
buffer being passed
• Return = size required to hold entire
string
4 ni.com
Route Specification Strings
Route specification strings are the paths connecting two channels and are composed of
one or more routes delimited by ampersands (
syntax, there are three defined routes or route groups:
routeOrGroup & routeOrGroup & routeOrGroup...
where routeOrGroup can be:
• Route name
• Route group name
• Two endpoint channels to be connected that are delimited by
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 channel can 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 (
(device/iviChan).
&). For example, in the following line of
->. NISE dynamically
/) delimiter. For example,
Note • Any channel, other than an endpoint, within a route specification
string
must
the endpoint channels
• Channels used as endpoints must
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:
be reserved for routing or directly hardwired to one of
.
not
be reserved for routing
• [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 VALUE
(HEX) (DECIMAL) DESCRIPTION
INTERNAL
FFFF8EB8 –29000 An internal error has occurred. Please contact National Instruments
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
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
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
EVAL_TIMED_OUT
FFFF8EAF –29008 NI Switch Executive is running with an evaluation license and the time
INVALID_NAME
FFFF8EAE –29009 The name contains invalid characters.
RUNTIME_IMPORTING_EVAL
FFFF8EAD –29010 This configuration was created with an evaluation license. Deployment
EVAL_EXPIRED_IMPORTING
FFFF8EAC –29011 NI Switch Executive cannot import configurations once the evaluation
RUNTIME_EXPORTING
FFFF8EAB –29012 NI Switch Executive deployment licenses cannot export configurations.
IMPORTING_FILE_ACCESS
FFFF8EAA –29013 There was an error when accessing (open or read) the NI Switch
technical support.
exist.
unavailable. Close other applications and try again.
be understood.
limit for this session has expired. Restart your application to continue
evaluating.
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.
period has expired.
The operation requested requires a development license.
Executive configuration file.
NI Switch Executive Quick Reference Guide
6 ni.com
VALUE VALUE
(HEX) (DECIMAL) DESCRIPTION
IMPORTING_FILE_FORMAT
FFFF8EA9 –29014 The file is not a valid NI Switch Executive configuration file.
INVALID_END_POINTS
FFFF8EA8 –29015 The endpoints of the path do not match the existing endpoints.
INVALID_PATH
FFFF8EA7 –29016 Cannot connect this path on the device.
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.
©
National Instruments Corporation
Error Codes
continued on the next page
7 NI Switch Executive Quick Reference Guide
Switch Control Functions
Miscellaneous Functions
Error Codes (continued)
VALUE VALUE
(HEX) (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
SOURCE_CHANNEL_CONFLICT
FFFF8E98 –29032 Connecting this route would cause excluded channels to be shorted
ROUTE_EXISTS_WITH_DIFFERENT_MODE
FFFF8E97 –29033 The route you are trying to connect already exists with a different
DISABLED_CHANNEL
FFFF8E96 –29034 The channel you are trying to use has been disabled for this virtual
CANNOT_CONNECT_TO_ITSELF
FFFF8E95 –29035 You cannot connect a channel to itself. Either your endpoint channels are
ROUTE_NOT_FOUND
FFFF8E94 –29036 Route cannot be found between the specified endpoints.
already in use by another route.
together.
multiconnect mode. It must be disconnected before you can make this
connection.
device.
the same or they reside on the same hardwire.
Programming Flow
The following diagram shows a typical programming flow for NI Switch Executive.
CVITM, IVITM,LabVIEWTM, National InstrumentsTM, NITM, ni.comTM, and TestStandTMare 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.txt file on your CD,
or ni.com/patents.
© 2001
–2004 National Instruments Corporation.
All rights reserved. Printed in Ireland.
*371308A-01*
371308A-01 Jul04
Loading...