NI SWITCH Scan Functions

Scan Functions

• niSwitch_SendSoftwareTrigger
• niSwitch_WaitForScanComplete
• niSwitch_Scan
• niSwitch_AbortScan
• niSwitch_ConfigureScanTrigger
• niSwitch_RouteTriggerInput
• niSwitch_IsScanning
• niSwitch_InitiateScan
• niSwitch_SetContinuousScan
• niSwitch_RouteScanAdvancedOutput
• niSwitch_ConfigureScanList

niSwitch_Scan

Specific Function

C Function Prototype

ViStatus niSwitch_Scan (ViSession vi, ViConstString scanlist, ViInt16 initiation);

Purpose

Takes the scan list provided, programs the switching hardware and initiates the scan. Once initiation is complete, the operation will return. The scan list itself is comprised of a list of channel connections separated by semicolons. For example, the following scan list would scan the first three channels of a multiplexer. Example: com0->ch0; com0->ch1; com0->ch2;. Refer to scan lists) for additional information. To see the status of the scan, you can call either niSwitch_IsScanning or niSwitch_WaitForScanComplete. Use the niSwitch_ConfigureScanTrigger function to configure the scan trigger. Use the niSwitch_AbortScan function to stop the scan if you are in continuous scan mode (Refer to niSwitch_SetContinuousScan); otherwise the scan halts automatically when the end of the scan list is reached. For reference, this operation is equivalent to calling niSwitch_ConfigureScanList and niSwitch_InitiateScan.

Parameters

Name	Type	Description
vi	ViSession	A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
scanlist	ViConstString	Pass the scan list) you want the instrument to use.
initiation	ViInt16	Use the initiation parameter to specify whether the switch or the measurement device initiates the scan trigger handshake. This parameter determines whether to wait for the scan to reach a trigger point before completing. If the measurement device initiates the scan, set this parameter to NISWITCH_VAL_MEASUREMENT_DEVICE_INITIATED. This function then waits until the switch is waiting for a trigger from the measurement device before completing. If the switch initiates the scan, set this parameter to NISWITCH_VAL_SWITCH_INITIATED. This function then completes immediately after initiating the scan. You should have already set up your DMM to wait for a trigger before calling this function with Initiation set to NISWITCH_VAL_SWITCH_INITIATED.

Value	Description
NISWITCH_VAL_SWITCH_INITIATED	Switch Initiated.
NISWITCH_VAL_MEASUREMENT_DEVICE_INITIATED (default)	Measurement device initiated.

Related Information

• niSwitch_InitiateScan
• Scan Lists

niSwitch_InitiateScan

IviSwtchScanner Capability Group

C Function Prototype

ViStatus niSwitch_InitiateScan (ViSession vi);

Purpose

Commits the configured scan list and trigger settings to hardware and initiates the scan. If niSwitch_Commit was called earlier, niSwitch_InitiateScan only initiates the scan and returns immediately.

Once the scanning operation begins, you cannot perform any other operation other than GetAttribute, niSwitch_AbortScan, or niSwitch_SendSoftwareTrigger. All other functions return the NISWITCH_ERROR_SCAN_IN_PROGRESS error. To stop the scanning operation,

To stop the scanning operation, call niSwitch_AbortScan.

Parameters

Name	Type	Description
vi	ViSession	A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.

Related Information

• niSwitch_Commit
• Scanning

niSwitch_AbortScan

IviSwtchScanner Capability Group

C Function Prototype

ViStatus niSwitch_AbortScan (ViSession vi);

Purpose

Aborts the scan in progress. The switch module returns to the state it was in before the scan was initiated.

Initiate a scan with niSwitch_InitiateScan.

If the switch module is not scanning, the NISWITCH_ERROR_NO_SCAN_IN_PROGRESS error is returned.

Parameters

Name	Type	Description
vi	ViSession	A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.

Related Information

• niSwitch Properties
• Scanning
• Writing a Software Trigger Scanning Program

niSwitch_SendSoftwareTrigger

IviSwtchSoftwareTrigger Capability Group

C Function Prototype

ViStatus niSwitch_SendSoftwareTrigger (ViSession vi);

Purpose

Sends a software trigger to the switch specified in the NI-SWITCH session. When the trigger input is set to NISWITCH_VAL_SOFTWARE_TRIG through either the niSwitch_ConfigureScanTrigger function or the NISWITCH_ATTR_TRIGGER_INPUT attribute, the scan does not proceed from a semicolon (wait for trigger) until niSwitch_SendSoftwareTrigger is called.

Parameters

Name	Type	Description
vi	ViSession	A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.

Related Information

• Scanning
• Software Trigger Scanning

niSwitch_IsScanning

IviSwtchScanner Capability Group

C Function Prototype

ViStatus niSwitch_IsScanning (ViSession vi, ViBoolean* isScanning);

Purpose

Indicates the status of the scan.

Parameters

Name	Type	Description
vi	ViSession	A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
isScanning	ViBoolean	NI-SWITCH returns the value of NISWITCH_ATTR_IS_SCANNING attribute. If VI_TRUE, the switch module is currently scanning through the scan list (i.e. it is not in the Idle state). If VI_FALSE, the switch module is not currently scanning through the scan list (i.e. it is in the Idle state).

Related Information

• Scanning

niSwitch_WaitForScanComplete

IviSwtchScanner Capability Group

C Function Prototype

ViStatus niSwitch_WaitForScanComplete (ViSession vi, ViInt32 maximumTime_ms);

Purpose

Pauses until the switch stops scanning or until the maximum time has elapsed, when NI-SWITCH returns a timeout error.

If the time you specify with the maximumTime_ms parameter elapsed before the scanning operation has finished, this function returns the NISWITCH_ERROR_MAX_TIME_EXCEEDED error.

Parameters

Name	Type	Description
vi	ViSession	A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
maximumTime_ms	ViInt32	Specifies the maximum length of time to wait for the switch module to stop scanning. If the specified time elapses before the scan ends, the NISWITCH_ERROR_MAX_TIME_EXCEEDED error is returned. The default value is 5000 ms.

Related Information

• Scanning

niSwitch_SetContinuousScan

IviSwtchScanner Capability Group

C Function Prototype

ViStatus niSwitch_SetContinuousScan (ViSession vi, ViBoolean continuousScan);

Purpose

Sets the to loop continuously through the scan list or to stop scanning after one pass through the scan list.

Parameters

Name	Type	Description
vi	ViSession	A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
continuousScan	ViBoolean	If VI_TRUE, loops continuously through the scan list during scanning. If VI_FALSE, the scan stops after one pass through the scan list. The default value is VI_FALSE.

Related Information

• Scanning

niSwitch_ConfigureScanList

IviSwtchScanner Capability Group

C Function Prototype

ViStatus niSwitch_ConfigureScanList (ViSession vi, ViConstString scanlist, ViInt32 scanMode);

Purpose

Configures the scan list and scan mode used for scanning.

Refer to Devices) to determine if the switch module supports scanning.

The scan list is comprised of a list of channel connections separated by semicolons. For example, the following scan list will scan the first three channels of a multiplexer:

com0->ch0; com0->ch1; com0->ch2;

Refer to Scan Lists) for more information on scan list syntax.

To see the status of the scan, call either niSwitch_IsScanning or niSwitch_WaitForScanComplete. Use the niSwitch_ConfigureScanTrigger function to configure the scan trigger. Use the niSwitch_InitiateScan function to start the scan.

Parameters

Name	Type	Description
vi	ViSession	A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
scanlist	ViConstString	The scan list to use. NI-SWITCH uses this value to set the NISWITCH_ATTR_SCAN_LIST attribute.
scanMode	ViInt32	Specifies how the switch module breaks existing connections when scanning. The driver uses this value to set the NISWITCH_ATTR_SCAN_MODE attribute. Refer to scan modes) for more information. The default value is NISWITCH_VAL_BREAK_BEFORE_MAKE.

Related Information

• Scan Lists
• Scanning

niSwitch_ConfigureScanTrigger

IviSwtchScanner Capability Group

C Function Prototype

ViStatus niSwitch_ConfigureScanTrigger (ViSession vi, ViReal64 scanDelay, ViInt32 triggerInput, ViInt32 scanAdvancedOutput);

Purpose

Configures the scan triggers for the scan list established with niSwitch_ConfigureScanList.

Refer to Devices) to determine if the switch module supports scanning.

niSwitch_ConfigureScanTrigger sets the location that the switch expects to receive an input trigger to advance through the scan list. This function also sets the location where it outputs a scan advanced signal after it completes an entry in the scan list.

Parameters

Name	Type	Description
vi	ViSession	A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
scanDelay	ViReal64	The minimum length of time you want the switch to wait after it creates a path until it asserts a trigger on the scan advanced output line. The driver uses this value to set the NISWITCH_ATTR_SCAN_DELAY attribute. The scan delay is in addition to the settling time. The driver uses this value to set the NISWITCH_ATTR_SCAN_DELAY attribute. Express this value in seconds. The default value is 0.0 s.
triggerInput	ViInt32	Trigger source you want the switch module to use during scanning. The driver uses this value to set the NISWITCH_ATTR_TRIGGER_INPUT attribute. The switch waits for the trigger you specify when it encounters a semicolon in the scan list. When the trigger occurs, the switch advances to the next entry in the scan list. Refer to NISWITCH_ATTR_TRIGGER_INPUT for a list of valid values.
scanAdvancedOutput	ViInt32	Output destination of the scan advanced trigger signal. NI-SWITCH uses this value to set the NISWITCH_ATTR_SCAN_ADVANCED_OUTPUT attribute. After the switch processes each entry in the scan list, it waits the length of time you specify in the scanDelay parameter and then asserts a trigger on the line you specify with this parameter. Refer to NISWITCH_ATTR_SCAN_ADVANCED_OUTPUT for a list of valid values.

Related Information

• Scanning

niSwitch_RouteTriggerInput

Specific Function

C Function Prototype

ViStatus niSwitch_RouteTriggerInput (ViSession vi, ViInt32 triggerInputConnector, ViInt32 triggerInputBusLine, ViBoolean invert);

Purpose

Routes the input trigger from the front or rear connector to a trigger bus line (TTLx). To disconnect the route, call this function again and specify None for trigger bus line parameter.

Parameters

Name	Type	Description
vi	ViSession	A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
triggerInputConnector	ViInt32	The location of the input trigger source on the switch module. Valid locations are the NISWITCH_VAL_FRONTCONNECTOR and NISWITCH_VAL_REARCONNECTOR. The default value is NISWITCH_VAL_FRONTCONNECTOR.
triggerInputBusLine	ViInt32	The trigger line to route the input trigger. Select NISWITCH_VAL_NONE to break an existing route. Valid Values: NISWITCH_VAL_NONE (default) NISWITCH_VAL_TTL0 NISWITCH_VAL_TTL1 NISWITCH_VAL_TTL2 NISWITCH_VAL_TTL3 NISWITCH_VAL_TTL4 NISWITCH_VAL_TTL5 NISWITCH_VAL_TTL6 NISWITCH_VAL_TTL7
invert	ViBoolean	If VI_TRUE, inverts the input trigger signal from falling to rising or vice versa. The default value is VI_FALSE.

Related Information

• Scanning
• niSwitch_ConfigureScanTrigger

niSwitch_RouteScanAdvancedOutput

Specific Function

C Function Prototype

ViStatus niSwitch_RouteScanAdvancedOutput (ViSession vi, ViInt32 scanAdvancedOutputConnector, ViInt32 scanAdvancedOutputBusLine, ViBoolean invert);

Purpose

Routes the scan advanced output trigger from a trigger bus line (TTLx) to the front or rear connector.

Parameters

Name	Type	Description
vi	ViSession	A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
scanAdvancedOutputConnector	ViInt32	The scan advanced output trigger destination. Valid Values: NISWITCH_VAL_FRONTCONNECTOR (default) NISWITCH_VAL_REARCONNECTOR.
scanAdvancedOutputBusLine	ViInt32	The trigger line to route the scan advanced output trigger from the front or rear connector. Select NISWITCH_VAL_NONE to break an existing route. Valid Values: NISWITCH_VAL_NONE (default) NISWITCH_VAL_TTL0 NISWITCH_VAL_TTL1 NISWITCH_VAL_TTL2 NISWITCH_VAL_TTL3 NISWITCH_VAL_TTL4 NISWITCH_VAL_TTL5 NISWITCH_VAL_TTL6 NISWITCH_VAL_TTL7
invert	ViBoolean	If VI_TRUE, inverts the input trigger signal from falling to rising or vice versa. The default value is VI_FALSE.

Related Information

• Scanning