Home > Language Reference > Classes > Stream

Write Method

Writes data to a stream.

Syntax

Public Sub Write(ByRef vValue As Boolean, Optional ByVal eSize As HbSerialize = hbWriteDefault)
Public Sub Write(ByRef vValue As Byte, Optional ByVal eSize As HbSerialize = hbWriteDefault)
Public Sub Write(ByRef vValue As Integer, Optional ByVal eSize As HbSerialize = hbWriteDefault)
Public Sub Write(ByRef vValue As Long, Optional ByVal eSize As HbSerialize = hbWriteDefault)
Public Sub Write(ByRef vValue As Single, Optional ByVal eSize As HbSerialize = hbWriteDefault)
Public Sub Write(ByRef vValue As Double, Optional ByVal eSize As HbSerialize = hbWriteDefault)
Public Sub Write(ByRef vValue As Date, Optional ByVal eSize As HbSerialize = hbWriteDefault)
Public Sub Write(ByRef vValue As String, Optional ByVal eSize As HbSerialize = hbWriteDefault)
Public Sub Write(ByRef vValue As Array, Optional ByVal eSize As HbSerialize = hbWriteDefault)
Public Sub Write(ByRef vValue As Object, Optional ByVal eSize As HbSerialize = hbWriteDefault)

Remarks

The Write method writes data to a stream while the Read function reads data from 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 value to write to the stream. The type of vValue determines which flavor of the Write 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:

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, the stream is padded with null bytes. If the eSize parameter specifies a value lesser than the size of the data type, the requested number of bytes are written, but the resulting value in the stream may be meaningless. For example:

Dim s As StreamMemory
Dim v As Integer

s.Write v, 5 ' Write the 2 bytes of v and then 3 null bytes
s.Write v, 1 ' Write 

Serialization of character strings

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

The hbWriteNoNull mode is useful when dealing with text files, or when dealing with remote servers through a StreamSocket object. In those cases, the termination character should be the newline character, not the null character. For example, the following statement sends a GET command to an HTTP server:

s.Write "GET www.handheld-basic.com HTTP/1.0\r\n", hbWriteNoNull

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, null bytes are appended. If the eSize parameter specifies a value lesser than the size of the array, the requested number of bytes are written, but not all the elements in the array may have been written. For example:

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

s.Write b, 5 ' Write 5 bytes. Only elements b(1) to b(5) will be written

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
Stream.Write tbl

is equivalent to:

Dim tbl As clsCustomer
Stream.Write tbl.Name
Stream.Write tbl.Zip
Stream.Write 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. HB++ does not provide any function to generate a Palm OS^® bitmap resource from a Bitmap object.

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

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

Writing a DatabaseInfo object into a stream serializes the database to which the object points. The storage format is compatible with the prc format if the database is a resource DB, and with the pdb format if the database is a record DB. Thus you can use the Write statement to save a database on an expansion card, or to send a database by infrared to another handheld device. The following example shows how to write an application capable of sending itself by infrared:

Private Sub Button1_Click()
  Dim exg As New StreamExg
  Dim dbi As DatabaseInfo
  
  Set dbi = App.Info
  exg.Connect dbi.Name & ".prc"
  Write exg, dbi
  exg.Disconnect
End Sub

The value of the eSize parameter is always ignored. The number of bytes written is always equal to the size of the corresponding pdb or prc file. You can estimate this size prior to actually serializing the database by calling the FileSize property.

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