ncAction

Purpose

Perform an action on an object.

Format

NCTYPE_STATUS

ncAction( NCTYPE_OBJH ObjHandle, NCTYPE_OPCODE Opcode, NCTYPE_UINT32 Param);

Input

ObjHandle

Object handle from ncOpenObject.

Opcode

Operation code indicating which action to perform.

Param

Parameter whose meaning is defined by Opcode.

Output

Return Value

Status of the function call, returned as a signed 32-bit integer. Zero means the function executed successfully. Negative specifies an error, meaning the function did not perform expected behavior. Positive specifies a warning, meaning the function performed as expected, but a condition arose that might require attention. For more information, refer to ncStatusToString.

Description

ncAction is a general purpose function you can use to perform an action on the object specified by ObjHandle. Its normal use is to start and stop network communication on a CAN Network Interface Object.

For the most frequently used and/or complex actions, NI-CAN provides functions such as ncOpenObject and ncRead. ncAction provides an easy, general purpose way to perform actions that are used less frequently or are relatively simple.

CAN Network Interface Object

NI-CAN propagates all actions on the CAN Network Interface Object up to all open CAN Objects. The following table describes the actions supported by the CAN Network Interface Object.

Actions Supported by the CAN or LIN Network Interface Object

Opcode	Param	Description
NC_OP_START (80000001 hex)	N/A (ignored)	Transitions network interface from stopped (idle) state to started (running) state. If network interface is already started, this operation has no effect. When a network interface is started, it is communicating on the network. When you execute NC_OP_START on a stopped CAN Network Interface Object, NI-CAN propagates it upward to all open higher-level CAN Objects. Thus, you can use it to start all higher-level network communication simultaneously.
NC_OP_STOP (80000002 hex)	N/A (ignored)	Transitions network interface from started state to stopped state. If network interface is already stopped, this operation has no effect. When a network interface is stopped, it is not communicating on the network. The stop action clears all entries from the read queue of the Network Interface Object. When you execute NC_OP_STOP on a running CAN Network Interface Object, NI-CAN propagates it upward to all open higher-level CAN Objects.
NC_OP_RESET (80000003 hex)	N/A (ignored)	Resets network interface. Stops network interface, then clears all entries from read and write queues. NC_OP_RESET is propagated up to all open higher-level CAN Objects.
NC_OP_RTSI_OUT (80000004 hex)	N/A (ignored)	Output a pulse or toggle on the RTSI line depending upon the NC_ATTR_RTSI_SIG_BEHAV. The NC_OP_RTSI_OUT action is not supported on the 847x or 847x with Sync series hardware.

CAN Object

All actions performed on a CAN Object affect that CAN Object alone, and do not affect other CAN Objects or communication as a whole.

The following table describes the actions supported by the CAN Object.

Actions Supported by the CAN Object

Opcode	Param	Description
NC_OP_START (80000001 hex)	N/A (ignored)	Transitions the CAN Object from stopped (idle) state to started (running) state. If the CAN Object is already started, this operation has no effect.
NC_OP_STOP (80000002 hex)	N/A (ignored)	Stops the CAN Object. For example, if the CAN Object is configured to transmit data frames periodically, this action stops the periodic transmissions. This action will also clear all entries from the read queue.
NC_OP_RESET (80000003 hex)	N/A (ignored)	Resets the CAN Object. Stops the CAN Object, then clears all entries from read and write queues.
NC_OP_RTSI_OUT (80000004 hex)	N/A (ignored)	Output a pulse or toggle on the RTSI line depending upon the NC_ATTR_RTSI_SIG_BEHAV.