Home > Language Reference > Classes > Stream

Read Function

Reads data from a stream.

Syntax

Public Function Read(ByRef vValue As Boolean, Optional ByVal eSize As HbSerialize = hbReadDefault) As Long
Public Function Read(ByRef vValue As Byte, Optional ByVal eSize As HbSerialize = hbReadDefault) As Long
Public Function Read(ByRef vValue As Integer, Optional ByVal eSize As HbSerialize = hbReadDefault) As Long
Public Function Read(ByRef vValue As Long, Optional ByVal eSize As HbSerialize = hbReadDefault) As Long
Public Function Read(ByRef vValue As Single, Optional ByVal eSize As HbSerialize = hbReadDefault) As Long
Public Function Read(ByRef vValue As Double, Optional ByVal eSize As HbSerialize = hbReadDefault) As Long
Public Function Read(ByRef vValue As Date, Optional ByVal eSize As HbSerialize = hbReadDefault) As Long
Public Function Read(ByRef vValue As String, Optional ByVal eSize As HbSerialize = hbReadDefault) As Long
Public Function Read(ByRef vValue As Array, Optional ByVal eSize As HbSerialize = hbReadDefault) As Long
Public Function Read(ByRef vValue As Object, Optional ByVal eSize As HbSerialize = hbReadDefault) As Long

Remarks

The Read function reads data from a stream while the Write method writes data to a stream. These operations are called serialization. All data types with the exception of the Variant type can be serialized. Objects can also be serialized, as long as they handle the Serialize event.

The serialization is always carried out starting from the current pointer position in the stream. Once the operation is complete, the stream pointer is increased by the number of serialized bytes. At any moment, you can get and modify the position of the stream pointer using the methods and properties of the Stream object.

The vValue parameter indicates the variable where to store the data being read. Although it is syntactically correct to pass a litteral constant or a property instead of a variable, the Read function will not work properly if this parameter is not a (possibly qualified) variable name. The type of vValue determines which flavor of the Read function is called and therefore, the behavior of the function. Refer to the discussion below for more information on serialization of basic types, strings and objects.

The eSize parameter indicates the number of bytes to read and some optional flags. It can be one of the following values:

Moreover, you can also add the hbReadNoException flag to any of the previous values, to prevent an error from being raised if the end of stream is encountered. Note that you must specify a size; you cannot simply pass hbReadNoException.

The Read function returns the number of bytes actually read. However, if this number is less than the number of requested bytes and the hbReadNoException flag was not specified, a runtime error is raised instead.

Serialization of basic data types

The table below describes the way HB++ serializes basic data types, with the exception of the string type which is described later on:

For data occupying more than a byte, the format used is the big-endian format, specific to the Motorola^® 68000 processor: the most significant bytes appear before the least significant ones. Enumerated types can also be serialized. Depending on the values defined in the enumeration, this data behaves like Byte, Integer or Long. Refer to the documentation on the Enum statement for more information.

If the eSize parameter specifies a value greater than the size of the data type, it is ignored. If the eSize parameter specifies a value lesser than the size of the data type, the requested number of bytes are read, but the resulting value in the vValue parameter may be meaningless. For example:

Dim s As StreamMemory
Dim v As Integer

s.Read v, 5 ' Read only 2 bytes, which is the size of v
s.Read v, 1 ' Read 1 byte. The value in v may be meaningless

Serialization of character strings

Three modes are available when reading a character string from a stream, depending on the value of the eSize parameter, as shown below:

The hbReadLine mode is typically used when dealing with text files or with high level protocols such as HTTP or FTP.

Serialization of arrays

You can only serialize arrays of basic type, namely Boolean, Byte, Integer, Long, Single, Double, Date and enumerated types. Elements in the array are serialized one by one following the order of the array indices.

If the eSize parameter specifies a value greater than the size of the array, it is ignored. If the eSize parameter specifies a value lesser than the size of the array, the requested number of bytes are read, but not all the elements in the array may have been read. For example:

Dim s As StreamMemory
Dim b(1 To 10) As Byte

s.Read b, 5 ' Read 5 bytes. Only elements b(1) to b(5) will receive a value.

Serialization of Recordset objects

When serializing an object deriving from the predefined Recordset class, the fields are serialized one by one. For example, if your project contains the table clsCustomer which has the fields Name, Zip and PhoneNumber, the following code:

Dim tbl As clsCustomer
s.Read tbl

is equivalent to:

Dim tbl As clsCustomer
s.Read tbl.Name
s.Read tbl.Zip
s.Read tbl.PhoneNumber

The eSize parameter is always ignored. Note: for performance or optimization reasons, HB++ can serialize the fields in a different order to their order in the table.

Serialization of Bitmap objects

A Bitmap object correctly initialized can be serialized. The stream will contain a header of 16 bytes, then the bits of the image itself. The format of this header is as follows:

The image itself is stored immediately after the header, line by line, from left to right and top to bottom. The start of a line is always aligned on an even address, each line being completed if necessary by a null byte.

This storage format is not compatible with the storage format used by Palm OS^® to store an image in the application resources. If you want to read an image from an application database, you should use the CreateFromResource function of the Bitmap object.

The number of bytes read depends on the size, depth, and density of the image. The value of the eSize parameter is always ignored.

Note: runtime errors can occur if you attempt to read from a stream an image whose number of bits per pixel is not supported by the device. This can occur for example if you use the Read and Write statements to transmit an image by infrared from a color device to a monochrome device.

Serialization of Stream objects

It is possible to serialize a stream in another stream. The data is simply read from the source stream and re-written into the destination stream. If the eSize parameter is specified, the exact number of bytes requested is transferred. Otherwise, the serialization continues until the end of the source stream is reached.

Reading the source stream starts from the current position of the stream pointer. After the transfer, the pointer is increased by the number of bytes transferred.

Serialization of DatabaseInfo objects

Reading a DatabaseInfo object creates in the storage heap a new database from a flat prc or pdb file. A prc or pdb file including the name and the properties of the database, you cannot specify the name nor any attribute of the database that will be created.

Note that the prc or pdb file format does not have a logical end-of-file: when reading, all the data from the current stream pointer to the end of the stream are considered as being part of the database to be created. This causes problem when reading from a stream that does not have a physical end, such as a TCP/IP socket or a serial port, or if the stream contains other data between the end of the serialized database and the end of the stream. In such a case, you can specify a value to the eSize parameter to limit the number of bytes being read.

You can refer to the MiniBrowser sample for more information on using the Read statement to receive a standard prc or pdb file from a HTTP server using a StreamSocket object, or to the Expansion Cards section to learn how to backup and restore a database to files located on an expansion card.

Serialization of other objects

No other HB++ predefined object is serializable, but you can create your own serializable classes, by allowing them to process the Serialize event.

System requirements