(Engine-Level Function)
| Description: | Writes a block of data to a stream. |
| Returns: | Boolean |
Usage:  |
Script Only. |
| Function Groups: | Stream and Socket |
| Related to: |
FWrite | PipeStream | SWrite |
| Format: |
BlockWrite(DestinationStream, SourceData [, ByteLimit ]) |
| Parameters: |
| DestinationStream |
| Required. Any expression that returns a stream value. |
| SourceData |
| Required. Any text or stream expression that specifies the block of data to write to Stream. |
| ByteLimit |
| Optional 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.
Returns TRUE on success and FALSE on failure.
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 as shown in the following example:
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 its 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.
