Embedded IDE Link™ CC

readmsg - Read messages from specified RTDX™ channel

Syntax

data = readmsg(rx,channelname,'datatype',siz,nummsgs,timeout)
data = readmsg(rx,channelname,'datatype',siz,nummsgs)
data = readmsg(rx,channelname,datatype,siz)
data = readmsg(rx,channelname,datatype,nummsgs)
data = readmsg(rx,channelname,datatype)

Description

data = readmsg(rx,channelname,'datatype',siz,nummsgs,timeout) reads nummsgs from a channel associated with rx. channelname identifies the channel queue, which must be configured for read access. Each message is the same type, defined by datatype. nummsgs can be an integer that defines the number of messages to read from the specified queue, or all to read all the messages present in the queue when you call the readmsg function. Each read message becomes an output matrix in data, with dimensions specified by the elements in vector siz. For example, when siz is [m n], reading 10 messages (nummsgs equal 10) creates 10 m-by-n matrices in data. Each output matrix in data must have the same number of elements (m x n) as the number of elements in each message. You must specify the type of messages you are reading by including the datatype argument. datatype supports strings that define the type of data you are expecting, as shown in the following table.

When you include the timeout input argument in the function, readmsg reads messages from the specified queue until it receives nummsgs, or until the period defined by timeout expires while readmsg waits for more messages to be available. When the desired number of messages is not available in the queue, readmsg enters a wait loop and stays there until more messages become available or timeout seconds elapse. The timeout argument overrides the global time-out specified when you create rx.

data = readmsg(rx,channelname,'datatype',siz,nummsgs) reads nummsgs from a channel associated with rx. channelname identifies the channel queue, which must be configured for read access. Each message is the same type, defined by datatype. nummsgs can be an integer that defines the number of messages to read from the specified queue, or all to read all the messages present in the queue when you call the readmsg function. Each read message becomes an output matrix in data, with dimensions specified by the elements in vector siz. When siz is [m n], reading 10 messages (nummsgs equal 10) creates 10 n-by-m matrices in data. Each output matrix in data must have the same number of elements (m x n) as the number of elements in each message. You must specify the type of messages you are reading by including the datatype argument. datatype supports six strings that define the type of data you are expecting.

data = readmsg(rx,channelname,datatype,siz) reads one data message because nummsgs defaults to one when you omit the input argument. readmsgs returns the message as a row vector in data.

data = readmsg(rx,channelname,datatype,nummsgs) reads the number of messages defined by nummsgs. data becomes a cell array of row matrices, data = {msg1,msg2,...,msg(nummsgs)}, because siz defaults to [1,nummsgs]; each returned message becomes one row matrix in the cell array. Each row matrix contains one element for each data value in the current message msg# = [element(1), element(2),...,element(l)] where l is the number of data elements in message. In this syntax, the read messages can have different lengths, unlike the previous syntax options.

data = readmsg(rx,channelname,datatype) reads one data message, returning a row vector in data. All of the optional input arguments — nummsgs, siz, and timeout — use their default values.

In all calling syntaxes for readmsg, you can set siz and nummsgs to empty matrices, causing them to use their default values — nummsgs = 1 and siz = [1,l], where l is the number of data elements in the read message.

Caution   If the time-out period expires before the output data matrix is fully populated, you lose all the messages read from the channel to that point.

Examples

cc = ticcs;
rx = cc.rtdx;
open(rx,'ichannel','w');
enable(rx,'ichannel');
open(rx,'ochannel','r');
enable(rx,'ochannel');
indata = 1:25; % Set up some data.
write(cc,0,indata,30);
outdata=read(cc,0,'double',25,10)

outdata =

  Columns 1 through 13 

   1   2   3   4   5   6   7   8   9  10  11  12  13

  Columns 14 through 25 

  14  15   16  17  18  19  20  21  22  23  24  25

Now use RTDX to read the messages into a 4-by-5 array called out_array.

number_msgs = msgcount(rx,'ochannel') % Check number of msgs 
                                      % in read queue.
out_array = cc.rtdx.readmsg('ochannel','double',[4 5])

See Also

read, readmat, writemsg

readmat

readnumeric