CAN_SetValue

PCAN-Basic

previous page next page

PCAN-Basic Documentation

CAN_SetValue

Sets a configuration or information value within a PCAN Channel.

Syntax

C++

TPCANStatus __stdcall CAN_SetValue(
        TPCANHandle Channel,
        TPCANParameter Parameter,
        void* Buffer,
        WORD BufferLength
);

Parameters

Parameters	Description
Channel	The handle of a PCAN Channel (see TPCANHandle).
Parameter	The code of the value to be set (see TPCANParameter).
Buffer	The buffer containing the value to be set.
BufferLength	The length in bytes of the given buffer.

Returns

The return value is a TPCANStatus code. PCAN_ERROR_OK is returned on success. The typical errors in case of failure are:

PCAN_ERROR_ILLPARAMVAL:	Indicates that the parameters passed to the function are invalid. Check the parameter 'Buffer'; it should point to a valid data container for the requested value.
PCAN_ERROR_CAUTION:	The configuration of a parameter failed due to a no more existing channel. The parameter has been reset on all existing channels.
PCAN_ERROR_INITIALIZE:	Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLPARAMTYPE:	Indicates that the requested information is not available for the given PCAN Channel. Check the value of 'Parameter'; some values are not available for all PCAN-Channels or cannot be set.
PCAN_ERROR_ILLOPERATION:	An underlying process that is generated by a call to this function with the current parameters, is temporarily not allowed. The configuration in relation to the used TPCANParameter must be checked.

Remarks

Use the function CAN_SetValue to set configuration information or environment values of a PCAN Channel as parameters like the Message Filter and values like a custom entry in the log file of PCAN-Basic. Take in account that not all parameters are supported for all PCAN-Channels. The access's type of the parameters can also be different.

More information about the parameters and values that can be set can be found in Parameter Value Definitions.

Example

The following example shows the use of CAN_SetValue on the channel PCAN_USBBUS1 to insert a text into the PCAN-Basic log file. In case of failure, the returned code will be translated to a text (according with the operating system language) in English, German, Italian, French or Spanish, and it will be shown to the user.

Note: It is not needed to have an initialized PCAN channel for using the Log functionality.

C++:

TPCANStatus result;
char strMsg[256];

// Sets a text to be included in the Log file of the PCAN-Basic
//
strcpy(strMsg, "This is a custom text from an application included in PCAN-BASIC's Log File");

// Inserts the given text into the Log file of the PCAN-Basic.
// Note: If the Log functionality is disabled, this call will automatically
//activate the log process.
//
result = CAN_SetValue(PCAN_NONEBUS, PCAN_LOG_TEXT, strMsg, strlen(strMsg));
if(result != PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    CAN_GetErrorText(result, 0, strMsg);
    MessageBox(strMsg);
}
else
    MessageBox("The text was successfully logged in the PCAN-Basic's Log file.");