Read (FUN)¶

FUNCTION Read : CAA.HANDLE

Receives messages from a receiver.

Note

To avoid losing receive messages an application has to read all messages of all receivers each cycle. All messages should be processed and released by FreeMessage afterwards.

Note

Normally a receiver returns CAA.gc_hINVALID if all messages are read by application.
But receivers with xAlwaysNewest = TRUE return always the newest message even if it was already received.
The application has to free the message each time it is returned by CL2.Read!!!
In case of an always newest receiver the data pctMsgLeft points to should be interpreted as follows:
0: old message; 1: new message; 2: message overflow

Example

VAR
    hDriver : CAA.HANDLE;
    hReceiver : CAA.HANDLE;
    hMsg : CAA.HANDLE;
    ctMsgLeft : CAA.COUNT;
    eError : CL2.ERROR;
END_VAR

//Create a MaskReceiver which receives all messages with CAN ID 16#80.
hReceiver := CL2.CreateMaskReceiver(hDriver := hDriver,
                                    cobIdValue := 16#80, //cobID value
                                    cobIdMask := 16#FFFFFFFF, //cobID mask ==> all bits of value are relevant
                                    xRTRValue := FALSE, //no RTR messages
                                    xRTRMask := TRUE, //activate RTR filter ==> xRTRValue will be checked
                                    x29BitIdValue := FALSE, //no 29 bit CAN messages
                                    x29BitIdMask := TRUE, //activate 29 bit filter ==> x29BitIdValue will be checked
                                    xTransmitValue := FALSE, //only receive messages, no transmit message loopback
                                    xTransmitMask := TRUE, //activate transmit mask filter ==> xTransmitValue will be checked
                                    xAlwaysNewest := FALSE, //FALSE := receiver with queue; TRUE: only newest message
                                    eEvent := CB.EVENT.NO_EVENT, //no receive event
                                    xEnableSyncWindow := FALSE, //not implemented
                                    peError := ADR(eError) //optional pointer to error
);

REPEAT
    //receive a message from hReceiver
    hMsg := CL2.Read(hReceiverId := hReceiver, pctMsgLeft := ADR(ctMsgLeft), peError := ADR(eError));
    IF hMsg <> CAA.gc_hINVALID THEN
        //TODO: Process message (CL2.GetMessageDataPointer, CL2.GetMessageId, ...)
        CL2.FreeMessage(hMsg); //release message
        hMsg := CAA.gc_hINVALID; //to avoid using an already released message
    END_IF
UNTIL ctMsgLeft = 0
END_REPEAT

InOut:

Scope	Name	Type	Comment
Return	`Read`	`CAA.HANDLE`	handle of received CAN message or `CAA.gc_hINVALID` if receiver is empty.
Input	`hReceiverId`	`CAA.HANDLE`	receiver handle
	`pctMsgLeft`	POINTER TO CAA.COUNT	Optional pointer to `ctMsgLeft`. After calling `CL2.Read` `ctMsgLeft` contains the number of remaining messages in receive queue.
	`peError`	POINTER TO ERROR	optional pointer to error enum