TPCANParameter

PCAN-Basic

PCAN-Basic Documentation

TPCANParameter

Represents a PCAN parameter or a PCAN Value that can be read or set. According with the programming language, this type can be a group of defined values or an enumeration. With some exceptions, a channel must first be initialized before their parameters can be read or set.

Syntax

C++

#define TPCANParameter BYTE

#define PCAN_DEVICE_NUMBER 0x01
#define PCAN_5VOLTS_POWER 0x02
#define PCAN_RECEIVE_EVENT 0x03
#define PCAN_MESSAGE_FILTER 0x04
#define PCAN_API_VERSION 0x05
#define PCAN_CHANNEL_VERSION 0x06
#define PCAN_BUSOFF_AUTORESET 0x07
#define PCAN_LISTEN_ONLY 0x08
#define PCAN_LOG_LOCATION 0x09
#define PCAN_LOG_STATUS 0x0A
#define PCAN_LOG_CONFIGURE 0x0B
#define PCAN_LOG_TEXT 0x0C
#define PCAN_CHANNEL_CONDITION 0x0D
#define PCAN_HARDWARE_NAME 0x0E
#define PCAN_RECEIVE_STATUS 0x0F
#define PCAN_CONTROLLER_NUMBER 0x10
#define PCAN_TRACE_LOCATION 0x11
#define PCAN_TRACE_STATUS 0x12
#define PCAN_TRACE_SIZE 0x13
#define PCAN_TRACE_CONFIGURE 0x14
#define PCAN_CHANNEL_IDENTIFYING 0x15
#define PCAN_CHANNEL_FEATURES 0x16
#define PCAN_BITRATE_ADAPTING 0x17
#define PCAN_BITRATE_INFO = 0x18
#define PCAN_BITRATE_INFO_FD = 0x19
#define PCAN_BUSSPEED_NOMINAL = 0x1A
#define PCAN_BUSSPEED_DATA = 0x1B
#define PCAN_IP_ADDRESS = 0x1C
#define PCAN_LAN_SERVICE_STATUS = 0x1D
#define PCAN_ALLOW_STATUS_FRAMES = 0x1E
#define PCAN_ALLOW_RTR_FRAMES = 0x1F
#define PCAN_ALLOW_ERROR_FRAMES = 0x20
#define PCAN_INTERFRAME_DELAY = 0x21
#define PCAN_ACCEPTANCE_FILTER_11BIT = 0x22
#define PCAN_ACCEPTANCE_FILTER_29BIT = 0x23

Pascal OO

{$Z1}
TPCANParameter = (
    PCAN_DEVICE_NUMBER = 1,
    PCAN_5VOLTS_POWER = 2,
    PCAN_RECEIVE_EVENT = 3,
    PCAN_MESSAGE_FILTER = 4,
    PCAN_API_VERSION = 5,
    PCAN_CHANNEL_VERSION = 6,
    PCAN_BUSOFF_AUTORESET = 7,
    PCAN_LISTEN_ONLY = 8,
    PCAN_LOG_LOCATION = 9,
    PCAN_LOG_STATUS = 10,
    PCAN_LOG_CONFIGURE = 11,
    PCAN_LOG_TEXT = 12,
    PCAN_CHANNEL_CONDITION = 13,
    PCAN_HARDWARE_NAME = 14,
    PCAN_RECEIVE_STATUS = 15,
    PCAN_CONTROLLER_NUMBER = 16,
    PCAN_TRACE_LOCATION = 17,
    PCAN_TRACE_STATUS = 18,
    PCAN_TRACE_SIZE = 19,
    PCAN_TRACE_CONFIGURE = 20,
    PCAN_CHANNEL_IDENTIFYING = 21,
    PCAN_CHANNEL_FEATURES = 22,
    PCAN_BITRATE_ADAPTING = 23,
    PCAN_BITRATE_INFO = 24,
    PCAN_BITRATE_INFO_FD = 25,
    PCAN_BUSSPEED_NOMINAL = 26,
    PCAN_BUSSPEED_DATA = 27,
    PCAN_IP_ADDRESS = 28,
    PCAN_LAN_SERVICE_STATUS = 29,
    PCAN_ALLOW_STATUS_FRAMES = 30,
    PCAN_ALLOW_RTR_FRAMES = 31,
    PCAN_ALLOW_ERROR_FRAMES = 32,
    PCAN_INTERFRAME_DELAY = 33,
    PCAN_ACCEPTANCE_FILTER_11BIT = 34,
    PCAN_ACCEPTANCE_FILTER_29BIT = 35
);

public enum TPCANParameter : byte
{
    PCAN_DEVICE_NUMBER = 1,
    PCAN_5VOLTS_POWER = 2,
    PCAN_RECEIVE_EVENT = 3,
    PCAN_MESSAGE_FILTER = 4,
    PCAN_API_VERSION = 5,
    PCAN_CHANNEL_VERSION = 6,
    PCAN_BUSOFF_AUTORESET = 7,
    PCAN_LISTEN_ONLY = 8,
    PCAN_LOG_LOCATION = 9,
    PCAN_LOG_STATUS = 10,
    PCAN_LOG_CONFIGURE = 11,
    PCAN_LOG_TEXT = 12,
    PCAN_CHANNEL_CONDITION = 13,
    PCAN_HARDWARE_NAME = 14,
    PCAN_RECEIVE_STATUS = 15,
    PCAN_CONTROLLER_NUMBER = 16,
    PCAN_TRACE_LOCATION = 17,
    PCAN_TRACE_STATUS = 18,
    PCAN_TRACE_SIZE = 19,
    PCAN_TRACE_CONFIGURE = 20,
    PCAN_CHANNEL_IDENTIFYING = 21,
    PCAN_CHANNEL_FEATURES = 22,
    PCAN_BITRATE_ADAPTING = 23,
    PCAN_BITRATE_INFO = 24,
    PCAN_BITRATE_INFO_FD = 25,
    PCAN_BUSSPEED_NOMINAL = 26,
    PCAN_BUSSPEED_DATA = 27,
    PCAN_IP_ADDRESS = 28,
    PCAN_LAN_SERVICE_STATUS = 29,
    PCAN_ALLOW_STATUS_FRAMES = 30,
    PCAN_ALLOW_RTR_FRAMES = 31,
    PCAN_ALLOW_ERROR_FRAMES = 32,
    PCAN_INTERFRAME_DELAY = 33,
    PCAN_ACCEPTANCE_FILTER_11BIT = 34,
    PCAN_ACCEPTANCE_FILTER_29BIT = 35,
}

C++ / CLR

public enum class TPCANParameter : Byte
{
    PCAN_DEVICE_NUMBER = 1,
    PCAN_5VOLTS_POWER = 2,
    PCAN_RECEIVE_EVENT = 3,
    PCAN_MESSAGE_FILTER = 4,
    PCAN_API_VERSION = 5,
    PCAN_CHANNEL_VERSION = 6,
    PCAN_BUSOFF_AUTORESET = 7,
    PCAN_LISTEN_ONLY = 8,
    PCAN_LOG_LOCATION = 9,
    PCAN_LOG_STATUS = 10,
    PCAN_LOG_CONFIGURE = 11,
    PCAN_LOG_TEXT = 12,
    PCAN_CHANNEL_CONDITION = 13,
    PCAN_HARDWARE_NAME = 14,
    PCAN_RECEIVE_STATUS = 15,
    PCAN_CONTROLLER_NUMBER = 16,
    PCAN_TRACE_LOCATION = 17,
    PCAN_TRACE_STATUS = 18,
    PCAN_TRACE_SIZE = 19,
    PCAN_TRACE_CONFIGURE = 20,
    PCAN_CHANNEL_IDENTIFYING = 21,
    PCAN_CHANNEL_FEATURES = 22,
    PCAN_BITRATE_ADAPTING = 23,
    PCAN_BITRATE_INFO = 24,
    PCAN_BITRATE_INFO_FD = 25,
    PCAN_BUSSPEED_NOMINAL = 26,
    PCAN_BUSSPEED_DATA = 27,
    PCAN_IP_ADDRESS = 28,
    PCAN_LAN_SERVICE_STATUS = 29,
    PCAN_ALLOW_STATUS_FRAMES = 30,
    PCAN_ALLOW_RTR_FRAMES = 31,
    PCAN_ALLOW_ERROR_FRAMES = 32,
    PCAN_INTERFRAME_DELAY = 33,
    PCAN_ACCEPTANCE_FILTER_11BIT = 34,
    PCAN_ACCEPTANCE_FILTER_29BIT = 35,
};

Visual Basic

Public Enum TPCANParameter As Byte
    PCAN_DEVICE_NUMBER = 1
    PCAN_5VOLTS_POWER = 2
    PCAN_RECEIVE_EVENT = 3
    PCAN_MESSAGE_FILTER = 4
    PCAN_API_VERSION = 5
    PCAN_CHANNEL_VERSION = 6
    PCAN_BUSOFF_AUTORESET = 7
    PCAN_LISTEN_ONLY = 8
    PCAN_LOG_LOCATION = 9
    PCAN_LOG_STATUS = 10
    PCAN_LOG_CONFIGURE = 11
    PCAN_LOG_TEXT = 12
    PCAN_CHANNEL_CONDITION = 13
    PCAN_HARDWARE_NAME = 14
    PCAN_RECEIVE_STATUS = 15
    PCAN_CONTROLLER_NUMBER = 16
    PCAN_TRACE_LOCATION = 17
    PCAN_TRACE_STATUS = 18
    PCAN_TRACE_SIZE = 19
    PCAN_TRACE_CONFIGURE = 20
    PCAN_CHANNEL_IDENTIFYING = 21
    PCAN_CHANNEL_FEATURES = 22
    PCAN_BITRATE_ADAPTING = 23
    PCAN_BITRATE_INFO = 24
    PCAN_BITRATE_INFO_FD = 25
    PCAN_BUSSPEED_NOMINAL = 26
    PCAN_BUSSPEED_DATA = 27
    PCAN_IP_ADDRESS = 28
    PCAN_LAN_SERVICE_STATUS = 29
    PCAN_ALLOW_STATUS_FRAMES = 30
    PCAN_ALLOW_RTR_FRAMES = 31
    PCAN_ALLOW_ERROR_FRAMES = 32
    PCAN_INTERFRAME_DELAY = 33
    PCAN_ACCEPTANCE_FILTER_11BIT = 34
    PCAN_ACCEPTANCE_FILTER_29BIT = 35
End Enum

Python

TPCANParameter = c_ubyte

PCAN_DEVICE_NUMBER = TPCANParameter(0x01)
PCAN_5VOLTS_POWER = TPCANParameter(0x02)
PCAN_RECEIVE_EVENT = TPCANParameter(0x03)
PCAN_MESSAGE_FILTER = TPCANParameter(0x04)
PCAN_API_VERSION = TPCANParameter(0x05)
PCAN_CHANNEL_VERSION = TPCANParameter(0x06)
PCAN_BUSOFF_AUTORESET = TPCANParameter(0x07)
PCAN_LISTEN_ONLY = TPCANParameter(0x08)
PCAN_LOG_LOCATION = TPCANParameter(0x09)
PCAN_LOG_STATUS = TPCANParameter(0x0A)
PCAN_LOG_CONFIGURE = TPCANParameter(0x0B)
PCAN_LOG_TEXT = TPCANParameter(0x0C)
PCAN_CHANNEL_CONDITION = TPCANParameter(0x0D)
PCAN_HARDWARE_NAME = TPCANParameter(0x0E)
PCAN_RECEIVE_STATUS = TPCANParameter(0x0F)
PCAN_CONTROLLER_NUMBER = TPCANParameter(0x10)
PCAN_TRACE_LOCATION = TPCANParameter(0x11)
PCAN_TRACE_STATUS = TPCANParameter(0x12)
PCAN_TRACE_SIZE = TPCANParameter(0x13)
PCAN_TRACE_CONFIGURE = TPCANParameter(0x14)
PCAN_CHANNEL_IDENTIFYING = TPCANParameter(0x15)
PCAN_CHANNEL_FEATURES = TPCANParameter(0x16)
PCAN_BITRATE_ADAPTING = TPCANParameter(0x17)
PCAN_BITRATE_INFO = TPCANParameter(0x18)
PCAN_BITRATE_INFO_FD = TPCANParameter(0x19)
PCAN_BUSSPEED_NOMINAL = TPCANParameter(0x1A)
PCAN_BUSSPEED_DATA = TPCANParameter(0x1B)
PCAN_IP_ADDRESS = TPCANParameter(0x1C)
PCAN_LAN_SERVICE_STATUS = TPCANParameter(0x1D)
PCAN_ALLOW_STATUS_FRAMES = TPCANParameter(0x1E)
PCAN_ALLOW_RTR_FRAMES = TPCANParameter(0x1F)
PCAN_ALLOW_ERROR_FRAMES = TPCANParameter(0x20)
PCAN_INTERFRAME_DELAY = TPCANParameter(0x21)
PCAN_ACCEPTANCE_FILTER_11BIT = TPCANParameter(0x22)
PCAN_ACCEPTANCE_FILTER_29BIT = TPCANParameter(0x23)

Values

Name	Value	Data Type	Description
PCAN_DEVICE_NUMBER	1	Integer	PCAN-USB "device number" parameter.
PCAN_5VOLTS_POWER	2	Integer	PCAN-PC Card "5-volt power" parameter.
PCAN_RECEIVE_EVENT	3	Handle	PCAN receive event handler parameter.
PCAN_MESSAGE_FILTER	4	Integer	PCAN message filter parameter.
PCAN_API_VERSION	5	String	PCAN-Basic API version parameter.
PCAN_CHANNEL_VERSION	6	String	PCAN device channel version parameter.
PCAN_BUSOFF_AUTORESET	7	Integer	PCAN "reset on bus-off" parameter.
PCAN_LISTEN_ONLY	8	Integer	PCAN "listen-only" parameter.
PCAN_LOG_LOCATION	9	String	Directory path for log files.
PCAN_LOG_STATUS	10	Integer	Debug-Log activation status.
PCAN_LOG_CONFIGURE	11	Integer	Configuration of the debugged information (LOG_FUNCTION_***).
PCAN_LOG_TEXT	12	String	Custom insertion of text into the log file.
PCAN_CHANNEL_CONDITION	13	Integer	Availability status of a PCAN-Channel.
PCAN_HARDWARE_NAME	14	String	PCAN "hardware name" parameter.
PCAN_RECEIVE_STATUS	15	Integer	"Receive Status" parameter for incoming messages.
PCAN_CONTROLLER_NUMBER	16	Integer	Index of a CAN-Controller in a PCAN device.
PCAN_TRACE_LOCATION	17	String	Directory path for PCAN trace files.
PCAN_TRACE_STATUS	18	Integer	PCAN-Trace activation status.
PCAN_TRACE_SIZE	19	Integer	Configuration of the maximum size for a PCAN-Trace.
PCAN_TRACE_CONFIGURE	20	Integer	Configuration of the trace file storing modes (TRACE_FILE_***).
PCAN_CHANNEL_IDENTIFYING	21	Integer	USB Channel Identifying activation status.
PCAN_CHANNEL_FEATURES	22	Integer	Capabilities of a PCAN device (FEATURE_***).
PCAN_BITRATE_ADAPTING	23	Integer	Attachment to an existing connection with unknown/different bit rate.
PCAN_BITRATE_INFO	24	Integer	Current bit rate as BTR0BTR1 value (Standard CAN).
PCAN_BITRATE_INFO_FD	25	String	Current bit rate as FD String value (CAN-FD).
PCAN_BUSSPEED_NOMINAL	26	Integer	Current nominal CAN bus speed in bits/second.
PCAN_BUSSPEED_DATA	27	Integer	Current CAN data speed in bits/second.
PCAN_IP_ADDRESS	28	String	Remote address as a IPv4 formated string.
PCAN_LAN_SERVICE_STATUS	29	Integer	Running status of the LAN Service (Virtual PCAN-Gateway)
PCAN_ALLOW_STATUS_FRAMES	30	Integer	"Receive Status" parameter for Status frames.
PCAN_ALLOW_RTR_FRAMES	31	Integer	"Receive Status" parameter for RTR frames.
PCAN_ALLOW_ERROR_FRAMES	32	Integer	"Receive Status" parameter for Error frames.
PCAN_INTERFRAME_DELAY	33	Integer	Delay, in microseconds, between sending frames.
PCAN_ACCEPTANCE_FILTER_11BIT	34	64-Bit Integer	Acceptance filter over code and mask for 11-bit CAN IDs.
PCAN_ACCEPTANCE_FILTER_29BIT	35	64-Bit Integer	Acceptance filter over code and mask for 29-bit CAN IDs.

Characteristics

PCAN_DEVICE_NUMBER

Access:

Description: This parameter is used on PCAN-USB hardware to distinguish between 2 (or more) of them on the same computer. This value is persistent, i.e. the identifier will not be lost after disconnecting and connecting again the hardware.

Possible values: According with the Firmware version, this value can be a number in the range [1..255] or [1..4294967295]. If the Firmware has a resolution of one byte and the specified value is bigger, than the value is truncated.

Default value: If this parameter was never set before, the value is the maximum value possible for the used resolution. For 8-bits: 255 (FFh), for 32 bits: 429496729 (FFFFFFFFh).

PCAN-Device: PCAN-USB.

PCAN_5VOLTS_POWER

Access:

Description: This parameter is used on PCAN-PC Card hardware for switching the external 5V on the D-Sub connector of the PC Card. This is useful when connecting external bus converter modules to the card (AU5790 / TJA1054)).

Possible values: This parameter can have one of these values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: PCAN-PC Card, PCAN-HUB.

PCAN_RECEIVE_EVENT

Access:

Description: This parameter is used to let the PCAN driver notify an application when CAN messages are placed in its receive queue. In this form, message processing tasks of an application can react faster and make a more efficient use of the processor time.

Possible values: This value has to be a handle for an event object returned by the Windows API function CreateEvent or the value 0 (IntPtr.Zero in a managed environment). When setting this parameter, the value of 0 resets the parameter in the PCAN driver. When reading the value of 0 indicate that no event handle is set. For more information about reading with events, please refer to the topic Using Events.

Default value: Disabled (0).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_MESSAGE_FILTER

Access:

Description: This parameter allows the user to easy configure the message filter of a PCAN channel. With it is possible to fully open or complete close the filter.

Possible values: When setting only two values are possible: PCAN_FILTER_OPEN, PCAN_FILTER_CLOSE. When reading it is possible to receive a third value, PCAN_FILTER_CUSTOM, which indicates that the filter is configured to receive a custom range of IDs. Note that other values will considered invalid.

Default value: Complete opened (PCAN_FILTER_OPEN).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_API_VERSION

Access:

Description: This parameter is used to get information about the PCAN-Basic API implementation version.

Possible values: The value is a null-terminated string indication the version number of the API implementation. The returned text has the following form: x,x,x,x for major, minor, release and build. It represents the binary version of the API, within two 32-bit integers, defined by four 16-bit integers. The length of this text value will have a maximum length of 24 bytes, 5 bytes for represent each 16-bit value, three separator characters ( , or . ) and the null-termination.

Default value: NA.

PCAN-Device: NA. Any PCAN device can be used, including the PCAN_NONEBUS channel.

PCAN_CHANNEL_VERSION

Access:

Description: This parameter is used to get version information about the Driver of a PCAN Channel.

Possible values: The value is a null-terminated string which contains version number, driver name and copyright information about the driver used to handle with an specified PCAN channel. The length of the this text will have a maximum length of 256 bytes (null-termination included) .

Default value: NA.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel). Note: It is not needed to have a PCAN channel initialized before asking for its version.

PCAN_BUSOFF_AUTORESET

Access:

Description: This parameter instructs the PCAN driver to reset automatically the CAN controller of a PCAN channel when a bus-off state is detected. Since no communication is possible on a bus-off state, it is useful to let the driver to catch this event automatically and reset the controller, avoiding extra handling of this problem in an end application.

Possible values: This parameter can have one of these values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: Reseting the hardware has a duration of ~ 500 milliseconds. After receiving the PCAN_ERROR_BUSOFF error, an application should wait that time before trying to read or write again.

PCAN_LISTEN_ONLY

Access:

Description: This parameter allows the user to set a CAN hardware in Listen-Only mode. When this mode is set, the CAN controller doens't take part on active events (eg. transmit CAN messages) but stays in a passive mode (CAN monitor), in which it can analyse the traffic on the CAN bus used by a PCAN channel. See also the Philips Data Sheet "SJA1000 Stand-alone CAN controller".

Possible values: This parameter can have one of these values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS) containing a SJA1000 CAN controller.

REMARKS: This parameter can be used with an initialized or uninitialized channel. Configuring this parameter without having the channel initialized, does a so called "pre-initialization". This means that the channel will be set in Listen-Only mode as soon as possible, after it has been successfully connected, using CAN_Initialize (class-method: Initialize). Once the channel is disconnected, further initializations of this channel are done in normal mode. It is needed to set this parameter again before each initialization process, if the behavior described before is required. This is usefull to avoid or minimize arbitration problems when connecting to a CAN-network.

PCAN_LOG_LOCATION

Access:

Description: This value is used to set the folder location on a computer for the Log-File generated by the PCAN-Basic API, within a debug session. Setting this value starts recording debug information automatically. If a debug session is running (a log file is being written), PCAN_LOG_LOCATION instructs the API to close the current log file and to start the process again with the new folder information. Note that the name of the log file cannot be specified, this name is fixed as PCANBasic.log.

Possible values: This value must be a fully-qualified and valid path to an existing directory on the executing computer. There is no limit for the length of the string but it is recommended to use a length not bigger than MAX_PATH. For more information see Naming Files, Paths, and Namespaces.

Default value: Calling process's folder.

PCAN-Device: Default channel Only (PCAN_NONEBUS).

PCAN_LOG_STATUS

Access:

Description: This value is used to control the activity status of a debug session within the PCAN-Basic API. If the log status is set to ON without having set a location for the log file or without having configured the information to be traced, then the session process will start with the default values.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: Default channel Only (PCAN_NONEBUS).

PCAN_LOG_CONFIGURE

Access:

Description: This value is used to configure the debug information to be included in the log file generated in a debug session within the PCAN-Basic API.

Possible values: The value must be one of the following values or a combination of them:

LOG_FUNCTION_DEFAULT: This value is always active. It defines the default information to be traced, which is an unexpected exception like a memory access violation. After having configured the log with more options, this value can be used to reset that configuration, setting the log with its default value again. This kind of entry is marked with the word "EXCEPTION"* in the log file.
LOG_FUNCTION_ENTRY: This value causes an entry in the log file each time an API function is entered. This kind of entry is marked with the word "ENTRY"* in the log file.
LOG_FUNCTION_PARAMETERS: This value causes an entry in the log file each time an API function is entered, showing the name of the parameters passed to the function as well as their values. This kind of entry is marked with the word "PARAMETERS"* in the log file.
LOG_FUNCTION_LEAVE: This value causes an entry in the log file each time an API function is abandoned. This kind of entry is marked with the word "EXIT"* in the log file.
LOG_FUNCTION_WRITE: This value causes an entry in the log file each time a CAN message is written, using the function CAN_Write (class-method: Write). This kind of entry is marked with the word "CHANNEL 0xXX (Y)"* in the log file, where XX is the channel number in hex notation, and Y the word "OUT"* denoting the direction (outgoing). The complete CAN message is also represented as hex text.
LOG_FUNCTION_READ: This value causes an entry in the log file each time a CAN message is read, using the functions CAN_Read/CAN_ReadFD (class-methods: Read, ReadFD). This kind of entry is marked with the word "CHANNEL 0xXX (Y)"* in the log file, where XX is the channel number in hex notation, and Y the word "IN"* denoting the direction (incoming). The complete CAN message is also represented as hex text.

* Note that the PCAN-Basic API supports several languages. The log file use the language of the operating system. If this language is not one of the supported languages, than English is used.

* These words are always written in English, independently of the operating system's language.

Default value: Exceptions and Errors (LOG_FUNCTION_DEFAULT).

PCAN-Device: Default channel Only (PCAN_NONEBUS).

PCAN_LOG_TEXT

Access:

Description: This value is used to insert custom information in the log file generated in a debug session within the PCAN-Basic API. Setting this value starts recording debug information automatically.

This is very useful when it is desired to specially mark places of an application's execution path while debugging PCAN-Basic tasks. Furthermore, an application could use this feature as an own Log file. To do so, just use the default log's configuration (PCAN_LOG_CONFIGURE set to LOG_FUNCTION_DEFAULT) and include the desired information using PCAN_LOG_TEXT. In this way the log file will contain only user-defined debug information. Note that the name of the log file cannot be specified, this name is fixed as PCANBasic.log.

Possible values: This value must be a null-terminated string. There is no limit for the length of the string but it is recommended to use a length not bigger than MAX_PATH. For more information see Naming Files, Paths, and Namespaces.

Default value: NA.

PCAN-Device: Default channel Only (PCAN_NONEBUS).

PCAN_CHANNEL_CONDITION

Access:

Description: This parameter is used to check and detect available PCAN hardware on a computer, even before trying to connect any of them. This is useful when an application wants the user to select which hardware should be using in a communication session.

Possible values: This parameter can have one of these values: PCAN_CHANNEL_UNAVAILABLE, PCAN_CHANNEL_AVAILABLE, PCAN_CHANNEL_OCCUPIED, PCAN_CHANNEL_PCANVIEW.

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_HARDWARE_NAME

Access:

Description: This parameter is used to retrieve the name of the hardware represented by a PCAN channel. This is useful when an application wants to differentiate between several models of the same device, e.g. a PCAN-USB and a PCAN-USB Pro.

Possible values: The value is a null-terminated string which contains the name of the hardware specified by the given PCAN channel. The length of this text will have a maximum length of 32 bytes (null-termination included).

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: This parameter can be used with an initialized or uninitialized channel.

PCAN_RECEIVE_STATUS

Access:

Description: This parameter helps the user to allow / disallow the reception of messages within a PCAN Channel, regardless of the value of its reception filter. When the "Receive Status" is active (ON), incoming messages are forwarded to the user application through the CAN_Read/CAN_ReadFD functions (class-methods: Read, ReadFD). If "Receive Status" is deactivated (OFF), the incoming messages are disposed from the receive queue and each call to CAN_Read/CAN_ReadFD returns PCAN_ERROR_QRCVEMPTY. The acceptance filter of the channel remains unchanged (other applications working with the same PCAN-Hardware will not be disturbed).

Possible values: This parameter can have one of these values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Activated (PCAN_PARAMETER_ON).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS).

REMARKS: This parameter can be used with an initialized or uninitialized channel. Configuring this parameter without having the channel initialized, does a so called "pre-initialization". This means that the channel will set the configured "Receive Status" after it has been successfully connected, using CAN_Initialize (class-method: Initialize). Once the channel is disconnected, further initializations of this channel are done with the default value of this parameter (ON). This is usefull to avoid receiving messages immediately after connection, or before the receive filter is configured according with the needs of each application.

PCAN_CONTROLLER_NUMBER

Access:

Description: This parameter is a zero-based index used to identify the CAN controllers built in a hardware. This parameter is useful when it is needed to communicate with a specific physical channel on a multichannel CAN Hardware, e.g. "0" or "1" on a PCAN-USB Pro device.

Possible values: A number in the range [0..n-1], where n is the number of physical channels on the device being used.

Default value: NA.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: This parameter can be used with an initialized or uninitialized channel.

PCAN_TRACE_LOCATION

Access:

Description: This value is used to set the folder location on a computer for the PCAN-Trace file generated by the PCAN-Basic API, within a trace session. If a trace session is active (a trace file is being written), PCAN_TRACE_LOCATION instructs the API to close the current trace file and to start recording data again with the new folder information.

Default value: Calling process's folder.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: Note that the name of the trace file cannot be specified. The file uses the name of the current connection (PCAN-Channel's name) plus a file counter (e.g. PCAN_PCIBUS1_1.trc), though it can be enhanced by issuing the parameter PCAN_TRACE_CONFIGURE.

PCAN_TRACE_STATUS

Access:

Description: This value is used to control the activity status of a trace session within the PCAN-Basic API. If the trace status is set to ON without having set a location for the trace file or without having configured the storing mode, then the session process will start with the default values. Trying to activate a trace session can fail if overwriting is not set and a file with the same name already exists.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_TRACE_SIZE

Access:

Description: This value is used to set the maximum size, in megabytes, that a single trace file can have. Trying to set the size for a trace file will fail if the trace session is active.

Possible values: A number in the range [1..100], representing the amount of megabytes. Passing a value of 0 instructs the API to use the default value for this parameter. Trying to set a size bigger than 100 will fail.

Default value: 10 megabytes.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_TRACE_CONFIGURE

Access:

Description: This value is used to configure the trace process and the file generated in a trace session within the PCAN-Basic API. Trying to configure a trace file will fail if the trace session is active.

Possible values: The value must be one of the following values or a combination of them:

TRACE_FILE_SINGLE: This value represents the default trace configuration. It defines the use of a single trace file as output. When the tracing process starts, the file will be filled out with messages until the size of the file reaches the configured maximum size (see PCAN_TRACE_SIZE). The tracing process is then automatically stopped.
TRACE_FILE_SEGMENTED: This value indicates the API to keep tracing information by using several files. When the trace file being used reaches the maximum configured file size (see PCAN_TRACE_SIZE), then a new file is automatically created and the tracing process continues.
TRACE_FILE_DATE: This value instruct the API to use the start date information within the name of the trace file. The format used is YYYYMMDD, four digits for year, the next two for the month, and the last two for the day, e.g. "20130228_PCAN_USBBUS_1" for the 28th February 2013. If both, TRACE_FILE_DATE and TRACE_FILE_TIME are configured, the file name starts always with the date: "20130228140733_PCAN_USBBUS1_1.trc".
TRACE_FILE_TIME: This value instruct the API to use the start time information within the name of the trace file. The format used is HHMMSS, two digits for the hour (24 hours format), the next two for the minutes, and the last two for the seconds, e.g. "140733_PCAN_USBBUS_1" for 14:07:33 (02:07:33 PM). If both, TRACE_FILE_DATE and TRACE_FILE_TIME are configured, the file name starts always with the date: "20130228140733_PCAN_USBBUS1_1.trc".
TRACE_FILE_OVERWRITE: This value causes the overwriting of an existing trace file when a new trace session is started. If this value is not configured, trying to start a tracing process will fail, if the file name to generate is the same as one used by an existing file.

Default value: TRACE_FILE_SINGLE (Single file, not overwriting, with standard name).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_CHANNEL_IDENTIFYING

Access:

Description: This value is used to control the status of the "channel identifying procedure" on USB devices within the PCAN-Basic API. The procedure consists in blinking the LED associated to the given channel.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: This parameter can be used with an initialized or uninitialized channel. This identifying procedure is only available for USB based hardware (PCAN-USB, PCAN-USB Pro and PCAN-USB Hub). The blinking of the LED can be different according to the kind of hardware used (in color and blink rate). Only one channel can blink simultaneously.

PCAN_CHANNEL_FEATURES

Access:

Description: This value is used to read the particularities of a PCAN Channel.

Possible values: The value can be one of the following values or a combination of them:

FEATURE_FD_CAPABLE: This value indicates that the hardware represented by a PCAN Channel is FD capable (it supports flexible data rate).
FEATURE_DELAY_CAPABLE: This value indicates that the hardware represented by a PCAN Channel allows the configuration of a delay between sending frames.

Default value: A value of 0, indicating "no special features".

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: This parameter can be used with an initialized or uninitialized channel. FD Hardware must be initialized with CAN_InitializeFD (class-method: InitializeFD) in order to use their FD capabilities. In same way, the functions CAN_ReadFD (class-method: ReadFD) and CAN_WriteFD (class-method: WriteFD) have to be used for data transmission.

PCAN_BITRATE_ADAPTING

Access:

Description: This value is used to force an initialization process to succeed, even if the PCAN-Channel is being used by a PCAN-View with a different or unknown bit rate. The initialization function will return a PCAN_ERROR_CAUTION error, when the bit rate passed as parameter was different than that being used.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: All Plug-n-Play PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: This parameter can be set only on uninitialized channels. After connecting, an application can get the bit rate currently used by calling CAN_GetValue (class-method: GetValue) with the parameters PCAN_SPEED_QUERY, for standard CAN channels, or PCAN_SPEED_QUERY_FD for CAN-FD channels.

PCAN_BITRATE_INFO

Access:

Description: This value is used to read the currently configured communication speed, as BTR0-BTR1 value, of a PCAN Channel connected as standard CAN.

Possible values: A number in the range [0..65535] (Word Value).

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: This parameter can be used only on PCAN-Channels that have been initialized with the function CAN_Initialize (class-method: Initialize).

PCAN_BITRATE_INFO_FD

Access:

Description: This value is used to read the currently configured communication speed, as a parameterized string value (FD bit rate string), of a PCAN Channel connected as CAN FD.

Possible values: a String representing a FD bit rate. See FD Bit rate for more information.

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: This parameter can be used only on PCAN-Channels that have been initialized with the function CAN_InitializeFD (class-method: InitializeFD).

PCAN_BUSSPEED_NOMINAL

Access:

Description: This value is used to read the currently configured nominal CAN Bus speed, as bits/second.

Possible values: a number representing the nominal CAN bus speed being used, as the amount of bits that can be transmitted in a second.

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_BUSSPEED_DATA

Access:

Description: This value is used to read the currently configured CAN data speed (Bit Rate Switch), as bits/second.

Possible values: a number representing the CAN data speed configured for BRS, as the amount of bits that can be transmitted in a second.

Default value: N/A.

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: The speed used for data transmission is the same as the nominal speed on devices that don't support flexible data rate.

PCAN_IP_ADDRESS

Access:

Description: This value is used to read the address used by a device for IP communication.

Possible values: a string representing the IP address of a device, in IPv4 format.

Default value: N/A.

PCAN-Device: PCAN-LAN (PCAN-Gateway Ethernet/Wireless devices).

PCAN_LAN_SERVICE_STATUS

Access:

Description: This value is used to get the running status of the System-Service that is part of the Virtual PCAN-Gateway solution.

Possible values: This parameter can have one of these values: SERVICE_STATUS_RUNNING, SERVICE_STATUS_STOPPED.

Default value: N/A.

PCAN-Device: Default channel Only (PCAN_NONEBUS).

REMARKS: This parameter is only relevant in PCAN-LAN environments (using PCAN-Gateway Ethernet/Wireless devices).

PCAN_ALLOW_STATUS_FRAMES

Access:

Description: This parameter helps the user to allow / disallow the reception of messages of type "PCAN_MESSAGE_STATUS" within a PCAN Channel. When "PCAN_ALLOW_STATUS_FRAMES" is active (ON), generated Status messages are forwarded from the driver to the user application through the CAN_Read/CAN_ReadFD functions (class-methods: Read, ReadFD). Otherwise, the reception of Status frames is deactivated within the driver for this specific user application.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Enabled (PCAN_PARAMETER_ON).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_ALLOW_RTR_FRAMES

Access:

Description: This parameter helps the user to allow / disallow the reception of messages of type "PCAN_MESSAGE_RTR" within a PCAN Channel. When "PCAN_ALLOW_RTR_FRAMES" is active (ON), incoming RTR messages are forwarded to the user application through the CAN_Read/CAN_ReadFD functions (class-methods: Read, ReadFD). Otherwise, the reception of RTR frames is deactivated within the driver for this specific user application.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Enabled (PCAN_PARAMETER_ON).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_ALLOW_ERROR_FRAMES

Access:

Description: This parameter helps the user to allow / disallow the reception of messages of type "PCAN_MESSAGE_ERRFRAME" within a PCAN Channel. When "PCAN_ALLOW_ERROR_FRAMES" is active (ON), generated Error messages are forwarded from the driver to the user application through the CAN_Read/CAN_ReadFD functions (class-methods: Read, ReadFD ). Otherwise, the reception of Error frames is deactivated within the driver for this specific user application.

Possible values: The value must be one of the following values: PCAN_PARAMETER_OFF, PCAN_PARAMETER_ON. Note that other values will considered invalid.

Default value: Disabled (PCAN_PARAMETER_OFF).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

PCAN_INTERFRAME_DELAY

Access:

Description: This parameter is used to configure a delay, in microseconds, between sending frames. When this value is value is greater than 0, the driver includes that value as a pause between each written CAN frame. Otherwise, the CAN frames are sent as fast as possible.

Possible values: The parameter has a value range between [0..n], where n is the maximum value supported by the Firmware. If the maximum value supported by the firmware is lower than the entered one, the value will be truncated.

Default value: 0 (disabled).

PCAN-Device: All FPGA based PCAN devices.

PCAN_ACCEPTANCE_FILTER_11BIT

Access:

Description: This parameter is used to configure the reception filter of a PCAN channel with a specific 11-bit acceptance code and mask, as specified for the acceptance filter of the SJA1000 CAN controller. The acceptance code and mask are coded together in a 64-bit value, each of them using 4 bytes (Intel/Little-Endian format). The acceptance code is stored at the most significant bytes.

Possible values: Both parameter parts, code and mask, have a value range between [0..16838]. This means, the maximum value of this parameter as 64-bit value is 70364449226751, that is, hexadecimal 00003FFF00003FFFh. The mask uses the bit value '1' as "don't care bit".

Default value: 00000000000007FFh (no filtering).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

REMARKS: This parameter is particularly adapted to the SJA1000 CAN controller. Reception filters can also be configured with the function CAN_FilterMessages(class-method: FilterMessages). Note that after a PCAN Channel is initialized, the status of its filter is fully opened. According with the current filter status, setting this parameter causes the following behavior:

Filter status is PCAN_FILTER_OPEN: The filter is automatically closed and then configured with the given acceptance filter.
Filter status is PCAN_FILTER_CLOSE: The filter is set to the given acceptance filter.
Filter status is PCAN_FILTER_CUSTOM: The filter is expanded with the given acceptance filter. If a different acceptance code is required instead of expanding the current one, the filter has to be closed first before setting the acceptance filter. To do this use the parameter PCAN_MESSAGE_FILTER.

PCAN_ACCEPTANCE_FILTER_29BIT

Access:

Description: This parameter is used to configure the reception filter of a PCAN channel with a specific 29-bit acceptance code and mask, as specified for the acceptance filter of the SJA1000 CAN controller. The acceptance code and mask are coded together in a 64-bit value, each of them using 4 bytes (Intel/Little-Endian format). The acceptance code is stored at the most significant bytes.

Possible values: Both parameter parts, code and mask, have a value range between [0..4294967295]. This means, the maximum value of this parameter as 64-bit value is 18446744073709551615, that is, hexadecimal FFFFFFFFFFFFFFFFh. The mask uses the bit value '1' as "don't care bit".

Default value: 000000001FFFFFFFh (no filtering).

PCAN-Device: All PCAN devices (excluding PCAN_NONEBUS channel).

Filter status is PCAN_FILTER_OPEN: The filter is automatically closed and then configured with the given acceptance filter.
Filter status is PCAN_FILTER_CLOSE: The filter is set to the given acceptance filter.
Filter status is PCAN_FILTER_CUSTOM: The filter is expanded with the given acceptance filter. If a different acceptance code is required instead of expanding the current one, the filter has to be closed first before setting the acceptance filter. To do this use the parameter PCAN_MESSAGE_FILTER.