Main Content

read

Read data from remote host over TCP/IP

collapse all in page

    Syntax

    data = read(t)
    data = read(t,count)
    data = read(t,count,datatype)

    Description

    data = read(t) reads all available numeric or ASCII data from the remote host specified by the TCP/IP client t and returns the data as a row or column vector of doubles or text. The number of values read is specified by the NumBytesAvailable property of t. The function suspends MATLAB® execution until the specified number of values are read or a timeout occurs.

    example

    data = read(t,count) reads count number of values and returns the data.

    data = read(t,count,datatype) reads count number of values in the form specified by datatype and returns the data. The datatype argument is a character vector of a standard MATLAB data type.

    example

    Examples

    collapse all

    Open Live Script

    Create a TCP/IP client connection called t, connecting to a TCP/IP echo server with port 4000. To do so, you must have an echotcpip server running on port 4000.

    echotcpip("on",4000)
t = tcpclient("localhost",4000)
    t = 
  tcpclient with properties:

              Address: 'localhost'
                 Port: 4000
    NumBytesAvailable: 0

  Show all properties, functions

    The write function synchronously writes data to the remote host connected to t. First specify the data and then write the data. The function suspends MATLAB execution until the specified number of values is written to the remote host.

    Assign 10 bytes of uint8 data to the variable data.

    data = uint8(1:10)
    data = 1×10 uint8 row vector

    1    2    3    4    5    6    7    8    9   10

    View the data.

    whos data
      Name      Size            Bytes  Class    Attributes

  data      1x10               10  uint8

    Write data to the echo server.

    write(t,data)

    Confirm the success of the writing operation by viewing the NumBytesAvailable property.

    t.NumBytesAvailable
    ans = 10

    Since the client is connected to an echo server, the data you write to the server is returned to the client. Read all the bytes of data available.

    read(t)
    ans = 1×10 uint8 row vector

    1    2    3    4    5    6    7    8    9   10

    Using the read function with no arguments reads all available bytes of data from t connected to the remote host and returns the data. The number of values read is determined by the NumBytesAvailable property, which is the number of bytes available in the input buffer.

    Close the connection between the TCP/IP client and the remote host by clearing the object. Turn off the echotcpip server.

    clear t
echotcpip("off")
    Open Live Script

    Create a TCP/IP client connection called t, connecting to a TCP/IP echo server with port 4000. To do so, you must have an echotcpip server running on port 4000.

    echotcpip("on",4000)
t = tcpclient("localhost",4000)
    t = 
  tcpclient with properties:

              Address: 'localhost'
                 Port: 4000
    NumBytesAvailable: 0

  Show all properties, functions

    The write function synchronously writes data to the remote host connected to t. First specify the data and then write the data. The function waits until the specified number of values is written to the remote host.

    Assign 10 bytes of data to the variable data.

    data = (1:10)
    data = 1×10

     1     2     3     4     5     6     7     8     9    10

    View the data.

    whos data
      Name      Size            Bytes  Class     Attributes

  data      1x10               80  double

    Write data to the echo server.

    write(t,data)

    Confirm the success of the writing operation by viewing the NumBytesAvailable property.

    t.NumBytesAvailable
    ans = 80

    For any read or write operation, the data type is converted to uint8 for the data transfer. After the transfer, the data type reverts to the specified datatype. Since one double equals eight uint8 bytes, there are 80 bytes available.

    Since the client is connected to an echo server, the data you write to the server is returned to the client. Read 10 doubles from the server. The object name is always the first argument. The size argument must be the second argument, and datatype must be the third argument.

    read(t,10,"double")
    ans = 1×10

     1     2     3     4     5     6     7     8     9    10

    Close the connection between the TCP/IP client and the remote host by clearing the object. Turn off the echotcpip server.

    clear t
echotcpip("off")

    Input Arguments

    collapse all

    TCP/IP client, specified as a tcpclient object.

    Example: read(t) reads all available data from the TCP/IP client t.

    Number of values to read, specified as a positive integer value. If count is greater than the NumBytesAvailable property of t, the function suspends MATLAB execution and waits until the specified amount of data is read or a timeout occurs.

    Example: read(t,5) reads five values of uint8 data.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Size and format of each value, specified as a character vector or string. datatype determines the number of bytes to read for each value and the interpretation of those bytes as a MATLAB data type.

    Example: read(t,10,"double") reads 10 values of double data.

    Data Types: char | string

    Extended Capabilities

    C/C++ Code Generation
    Generate C and C++ code using MATLAB® Coder™.

    Version History

    Introduced in R2014b

    See Also

    Functions

    Topics