ApiSetValue(PcanChannel, PcanParameter, String) Method

Configures a string parameter value of a PCAN Channel.

Definition

Namespace: Peak.Can.Basic
Assembly: PCANBasic.NET (in PCANBasic.NET.dll) Version: 4.9.0

public static PcanStatus SetValue(
	PcanChannel channel,
	PcanParameter parameter,
	string buffer
)

Public Shared Function SetValue ( 
	channel As PcanChannel,
	parameter As PcanParameter,
	buffer As String
) As PcanStatus

C++

public:
static PcanStatus SetValue(
	PcanChannel channel, 
	PcanParameter parameter, 
	String^ buffer
)

Parameters

channel PcanChannel: The handle of a PCAN Channel.
parameter PcanParameter: The parameter whose value is to be configured.
buffer String: Contains the string value to be set.

Return Value

PcanStatus

OK is returned on success. The typical errors in case of failure are:

IllegalHandle: Indicates that the channel contains an invalid value.
Initialize: Indicates that the channel cannot be used because it was not found in the list of reserved Channels of the calling application.
IllegalHardwareHandle: Indicates that the hardware represented by channel is currently not available (detached or disabled).
InvalidParameter: Indicates that the requested parameter value is not implemented or is not supported by the given PCAN Channel.
InvalidValue: Indicates that one or more of the values passed to the method are invalid.

Remarks

Use SetValue(PcanChannel, PcanParameter, UInt64) to set the value of parameters like the LogLocation, and TraceLocation, among others.

Not all parameters are supported for all PCAN Channels. Using a parameter with a non-compatible Channel ends with an error.

Not all parameters have write access. Using a read-only parameter with SetValue ends with an error.

Except for a few parameters, the channel has to be initialized first, before being able to configure a value on it. For more information see the PcanParameter section.

Example

The following example shows the use of the SetValue(PcanChannel, PcanParameter, String) method using the default Channel (None). A custom location path for the log file is configured, the logging functionality activated, and a custom entry written.

Note

Changing the value of the parameter LogLocation automatically activates the logging functionality.

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.

PcanChannel channel = PcanChannel.None;
string path = System.IO.Path.GetTempPath();

// The temporary folder will be configured as output for the log file
//            
PcanStatus result = Api.SetValue(channel, PcanParameter.LogLocation, path);
if (result != PcanStatus.OK)
{
    // An error occurred
    //
    Api.GetErrorText(result, out var errorText);
    Console.WriteLine(errorText);
}
else
{
    // The path was changed and the logging functionality activated 
    //
    Console.WriteLine($"PCANBasic.log file location set to: {path}");
    Console.WriteLine("Calls to the PCAN-Basic are being logged...");                

    result = Api.SetValue(channel, PcanParameter.LogText, "This is a custom entry.");
    if (result != PcanStatus.OK)
    {
        // An error occurred
        //
        Api.GetErrorText(result, out var errorText);
        Console.WriteLine(errorText);
    }
    else
    {
        Console.WriteLine($"A custom text was included in the file {path}PCANBasic.log.");
    }
}

Dim channel As PcanChannel = PcanChannel.None
Dim path As String = IO.Path.GetTempPath()

' The temporary folder will be configured as output for the log file
'            
Dim result As PcanStatus = Api.SetValue(channel, PcanParameter.LogLocation, path)
' An error occurred
'
Dim errorText = Nothing
If result <> PcanStatus.OK Then
    Api.GetErrorText(result, errorText)
    Console.WriteLine(errorText)
Else
    ' The path was changed and the logging functionality activated 
    '
    Console.WriteLine($"PCANBasic.log file location: {path}")
    Console.WriteLine("Calls to the PCAN-Basic are being logged...")

    result = Api.SetValue(channel, PcanParameter.LogText, "This is a custom entry.")
    If result <> PcanStatus.OK Then
        Api.GetErrorText(result, errorText)
        Console.WriteLine(errorText)
    Else
        Console.WriteLine($"A custom text was included in the file {path}PCANBasic.log.")
    End If
End If

C++

PcanChannel channel = PcanChannel::None;
String^ path = System::IO::Path::GetTempPath();
String^ errorText;

// The temporary folder will be configured as output for the log file
//            
PcanStatus result = Api::SetValue(channel, PcanParameter::LogLocation, path);
if (result != PcanStatus::OK)
{
    // An error occurred
    //
    Api::GetErrorText(result, errorText);
    Console::WriteLine(errorText);
}
else
{
    // The path was changed and the logging functionality activated 
    //
    Console::WriteLine("PCANBasic.log file location set to: {0}", path);
    Console::WriteLine("Calls to the PCAN-Basic are being logged...");

    result = Api::SetValue(channel, PcanParameter::LogText, "This is a custom entry.");
    if (result != PcanStatus::OK)
    {
        // An error occurred
        //
        Api::GetErrorText(result, errorText);
        Console::WriteLine(errorText);
    }
    else
    {
        Console::WriteLine("A custom text was included in the file {0}PCANBasic.log.", path);
    }
}

Exceptions

DllNotFoundException	The underlying PCANBasic.dll library could not be found.
PcanBasicException	The execution of a PCAN-Basic related check operation ended with an unexpected result. Typically, this exception is triggered when a device driver is not installed or is not up to date.