PCANBasicWriteXL Method

Sends a CAN XL message to the specified channel.

Definition

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

C#

public static TPCANStatus WriteXL(
	ushort Channel,
	ref TPCANMsgXL MessageBuffer
)

VB

Public Shared Function WriteXL ( 
	Channel As UShort,
	ByRef MessageBuffer As TPCANMsgXL
) As TPCANStatus

C++

public:
static TPCANStatus WriteXL(
	unsigned short Channel, 
	TPCANMsgXL% MessageBuffer
)

Parameters

Channel UInt16: The handle of a PCAN Channel (see PCAN Handle Definitions).
MessageBuffer TPCANMsgXL: A buffer containing the CAN XL message to be sent.

Return Value

TPCANStatus

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

PCAN_ERROR_INITIALIZE: Indicates that the given PCAN channel was not found in the list of initialized channels of the calling application.
PCAN_ERROR_ILLPARAMVAL: Indicates that one or more parameters passed to the method are invalid.
PCAN_ERROR_ILLOPERATION: Indicates that the PCAN Channel passed to the method was not initialized using the InitializeXL method.
PCAN_ERROR_ILLHANDLE: Indicates that the given PCAN Channel is not valid.
PCAN_ERROR_BUSOFF: Indicates a bus error within the given PCAN Channel. The hardware is in bus-off status.
PCAN_ERROR_QXMTFULL: Indicates that the transmit queue of the Channel is full.

Remarks

Important

The use of Write, WriteFD and WriteXL depends on the kind of initialization. The PCAN Channel passed to this method must be initialized using the InitializeXL method. Otherwise the error PCAN_ERROR_ILLOPERATION is returned.

When the hardware status is bus-off, an application cannot communicate anymore. Consider using the PCAN_BUSOFF_AUTORESET parameter, which instructs the API to automatically reset the CAN controller when a bus-off state is detected.

Another way to reset errors like bus-off, bus-warning and bus-passive:

Performing an uninitialize / initialize cycle: This causes a hardware reset, but only when no more clients are connected to that channel.
Using the parameter PCAN_HARD_RESET_STATUS: It instructs this method to explicitly perform a hardware reset regardless of whether other clients are connected to that channel.

Example

The following example shows the use of WriteXL(UInt16, TPCANMsgXL) method on the channel PCAN_USBBUS1. 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 assumed that the channel was already initialized.

C#

TPCANStatus result;
System.Text.StringBuilder strMsg;
TPCANMsgXL msg;

strMsg = new System.Text.StringBuilder(256);

// ... channel is initialized ...

// A CAN message is created. The Data field (2048 bytes)
// of the message must also be created
//
msg = new TPCANMsgXL();
msg.DATA = new Byte[PCANBasic.MAX_LENGTH_DATA_XL];

// A CAN message is configured
//
msg.PID = 0x01;
msg.MSGTYPE = TPCANMessageTypeXL.PCAN_MESSAGE_XL;

// DLC 2047 means 2048 data bytes
//
msg.DLC = 2047;
for (int i = 0; i < PCANBasic.MAX_LENGTH_DATA_XL; i++)
    msg.DATA[i] = (byte)(i % byte.MaxValue);

// The message is sent using the PCAN-USB Channel 1
//
result = PCANBasic.WriteXL(PCANBasic.PCAN_USBBUS1, ref msg);
if (result != TPCANStatus.PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic.GetErrorText(result, 0, strMsg);
    Console.WriteLine(strMsg.ToString());
}
else
    Console.WriteLine("Message sent successfully");

VB

Dim result As TPCANStatus
Dim strMsg As System.Text.StringBuilder
Dim msg As TPCANMsgXL

strMsg = New System.Text.StringBuilder(256)

' ... channel is initialized ...

' A CAN message is created. The Data field (2048 bytes)
' of the message must also be created
'
msg = New TPCANMsgXL
msg.DATA = CType(Array.CreateInstance(GetType(Byte), PCANBasic.MAX_LENGTH_DATA_XL), Byte())

' A CAN message is configured
'
msg.PID = &H1
msg.MSGTYPE = TPCANMessageTypeXL.PCAN_MESSAGE_XL

' DLC 2047 means 2048 data bytes
'
msg.DLC = 2047
For i As Integer = 0 To PCANBasic.MAX_LENGTH_DATA_XL - 1
    msg.DATA(i) = CByte(i Mod Byte.MaxValue)
Next

' The message is sent using the PCAN-USB Channel 1
'
result = PCANBasic.WriteXL(PCANBasic.PCAN_USBBUS1, msg)
If result <> TPCANStatus.PCAN_ERROR_OK Then
    ' An error occurred, get a text describing the error and show it
    '
    PCANBasic.GetErrorText(result, 0, strMsg)
    Console.WriteLine(strMsg.ToString)
Else
    Console.WriteLine("Message sent successfully")
End If

C++

TPCANStatus result;
System::Text::StringBuilder^ strMsg;
TPCANMsgXL^ msg;

strMsg = gcnew System::Text::StringBuilder(256);

// ... channel is initialized ...

// A CAN message is created. The Data field (2048 bytes)
// of the message must also be created
//
msg = gcnew TPCANMsgXL();
msg->DATA = gcnew array<Byte>(PCANBasic::MAX_LENGTH_DATA_XL);

// A CAN message is configured
//
msg->PID = 0x01;
msg->MSGTYPE = TPCANMessageTypeXL::PCAN_MESSAGE_XL;

// DLC 2047 means 2048 data bytes
//
msg->DLC = 2047;
for (int i = 0; i < PCANBasic::MAX_LENGTH_DATA_XL; i++)
    msg->DATA[i] = (Byte)(i % Byte::MaxValue);

// The message is sent using the PCAN-USB Channel 1
//
result = PCANBasic::WriteXL(PCANBasic::PCAN_USBBUS1, *msg);
if (result != TPCANStatus::PCAN_ERROR_OK)
{
    // An error occurred, get a text describing the error and show it
    //
    PCANBasic::GetErrorText(result, 0, strMsg);
    Console::WriteLine(strMsg->ToString());
}
else
    Console::WriteLine("Message sent successfully");

PCANBasicWriteXL Method

Definition

Parameters

Return Value

Remarks

Example

See Also

Reference

Other Resources