chRead (Function)

The "chRead()" function will read a message from the specified channel.

If there is no message present in the channel, the calling thread will be blocked due to waiting for another thread to write a message by using the chWrite() function. Optionally, a timeout for the read operation can be specified.

Also see chWrite() and the section on Using Multithreading.

Special note on writing strings to a channel:

A STRING cannot be written directly to a channel with chWrite() but must be converted into pure memory with the strToMemory() function before being written to a channel. When this message is received by chRead(), it can be converted back to a string again by using the strToMemory() function.

Input:

ch : CHANNEL

The channel to read the message from.                

msg : PTR

Pointer to buffer where the message is to be stored.

lenmax : INT

Size of the buffer that msg points to.

If the size of the message in the channel is larger than lenmax, only lenmax bytes will be read. The remaining part of the message will be lost in this case.

timeout : INT (default: -1)

The time, in ms, to wait while trying to read data from the channel.

Use -1 to wait forever. This is the default.

Returns: INT

Declaration:

FUNCTION chRead : INT;
VAR_INPUT
  ch     : CHANNEL;
  msg     : PTR;
  lenmax : INT;
  timeout : INT := -1;
END_VAR;

Example:

INCLUDE rtcu.inc
 
VAR_INPUT
  al_1 : BOOL R_EDGE;
  al_2 : BOOL R_EDGE;
END_VAR;
 
VAR
  chalarm : CHANNEL;
END_VAR;
 
//SMS thread
THREAD_BLOCK smsalarm;
VAR
  alarmno : SINT;
END_VAR;
 
WHILE TRUE DO
  chRead(ch:=chalarm,msg:=ADDR(alarmno),lenmax:=SIZEOF(alarmno));
  gsmSendSMS(phonenumber := "22448899", message := strFormat(format:="Alarm. Door \1", v1:=alarmno));
END_WHILE;
 
END_THREAD_BLOCK;
 
 
PROGRAM test;
VAR
  smshandler : smsalarm;
  alarm     : sint;
END_VAR;
 
//main thread
chalarm := chInit(msgMax:=10);
smshandler();
gsmPower(power := TRUE);
BEGIN
  IF al_1 THEN
     alarm:=1;
     chWrite(ch:=chalarm,msg:=ADDR(alarm),len:=SIZEOF(alarm));
  END_IF;
  IF al_2 THEN
     alarm:=2;
     chWrite(ch:=chalarm,msg:=ADDR(alarm),len:=SIZEOF(alarm));
  END_IF;
END;
 
END_PROGRAM;