BlockWrite

Description:              This statement writes a block of data to a stream.

Returns:                    Nothing

Usage:                       Script

Format:                      BlockWrite(Stream, Data [, ByteLimit ])

Parameters:             Stream    { Stream }  { required }  { no default: }

                                                Any expression that returns a stream value.

                                    Data    { text or Stream }  { required }  { no default: }

                                                Any text or stream expression that specifies the block of data to write to Stream.

                                    ByteLimit    { numeric }  { optional }  { no default: }

                                                An optional parameter that is any numeric expression giving the maximum number of bytes copied from a stream.

Comments:               BlockWrite is more efficient than writing a block of data character-by-character. It is especially useful for named pipe streams when the intent is to send a block of bytes as a single message, rather than as a series of single-character messages (which is the result of using SWrite with the "%s" format option). If the second parameter is a stream value, the entire stream will be written to the first stream value.

Example:

if 1 NextState;

[

 stream = BuffStream("") { Open the first stream };

 SWrite(stream { Write to first stream },

        "%s %d %s" { Format for the data },

        "Test number: ", testNum, "is complete" { The data to write });

 file = FileStream("TestStatus" { Open second stream });

 Seek(stream, 0, 0) { Rewind the stream });

 BlockWrite(file, stream { Write from stream to file });

 CloseStream(stream);

]

The BlockWrite function can be used to copy files. An example is displayed below:

BlockWrite(FileStream ("File2.ext"), FileStream "File1.ext"));

When used in a manner similar to the example shown above, the BlockWrite statement is particularly useful in copying files (the DOS equivalent of "copy file1.ext file2.ext"), except in cases where File2 is larger than File1. In cases where File2 is larger than File1, the result (File2) will be it's original size. All the data from File1 will overwrite the beginning portion of the data in File2, with the remainder of the data originally contained in File2 remaining untouched.

If you require an exact copy of File1 (rather than the File1 data appended with the remaining File2 data), you can use an FWrite command to delete the destination file before calling BlockWrite.

See Also:

FWrite | PipeStream | SWrite