base.Channel.dataAvailable

Tests if some data can be read from the channel.

Syntax

dataAvailable()
  RETURNING result BOOLEAN

Usage

The dataAvailable() method returns TRUE if some data can be read from the channel.

This method is only to be used in some rare cases. Use dataAvailable() if the protocol allows asynchronous messages from the peer. An example is an asynchronous error message from the peer, to stop sending more data.

dataAvailable() checks if at least one byte is available on the stream. A subsequent read will block, if the read operation can not be completed. This should not happen: the methods read() and readLine() and their counterparts write() and writeLine() read and write complete lines (a line is a sequence of characters terminated by the line separator).

The method opens up the possibility to read data asynchronously. One possible use for this method is to stop a data transfer to a remote site after receiving an error message from the remote site.

Example

The local site sends a huge amount of data to the remote site using base.Channel.writeLine(). An error may occur during the processing of data by the remote side. The remote site writes an error message causing the local site to stop the data transmission.

On the local site, the file is parent.4gl.

-- this file: parent.4gl
MAIN
  DEFINE i INT
  DEFINE c base.Channel

  LET c = base.Channel.create()
  CALL c.openPipe("fglrun child", "u")
  WHILE TRUE
    IF c.dataAvailable() THEN
      DISPLAY "message from child: ", c.readLine()
      EXIT WHILE
    END IF
    CALL c.writeLine("line " || i)
  END WHILE
END MAIN

On the remote site, the file is child.4gl.

-- this file: child.4gl
MAIN
  DEFINE c base.Channel
  DEFINE s STRING
  DEFINE n INT

  LET n = 0
  LET c = base.Channel.create()
  CALL c.openFile("", "u")
  WHILE NOT c.isEof()
    LET s = c.readLine()
    LET n = n + 1
    IF n == 3 THEN
      CALL c.writeLine("error: something happens")
      CALL readRemainingData(c)
      EXIT WHILE
    END IF
  END WHILE
END MAIN

FUNCTION readRemainingData(c)
  DEFINE c base.Channel
  DEFINE s STRING
  WHILE NOT c.isEof()
    LET s = c.readLine()
  END WHILE
END FUNCTION