WriteBlock (Dataset subroutine)
Write a block of data to this dataset (Dataset class)
Syntax
dataset:WriteBlock( string) Throws WriteError
Syntax terms
| dataset | A reference to an instance of a Dataset object. |
|---|---|
| string | A longstring variable (though for small blocks, a regular string variable might suffice) that contains the block of data to be written. |
Usage notes
- To use the WriteBlock method, the Dataset object must be an output object, that is, its Output property must be True. Using WriteBlock against an input dataset results in request cancellation.
- The Dataset object must be in the Open state to use the WriteBlock method. Using WriteBlock against a dataset in the Closed or Full state results in request cancellation.
- If a WriteBlock method is used after a WriteRecord method, the block containing the record written by the preceding WriteRecord is written, if it has not already been written.
- The block written by WriteBlock must conform to the output file's format. That is, its length must be less than or equal to the BlockSize. For F format files, its length must be an exact multiple of the RecordLength value. For V and VB format files, the output string must have a binary BDW (Block Descriptor Word), and the individual records must be preceded by a binary RDW (Record Descriptor Word). This is true even under CMS, where records are not really stored on disks with BDWs and RDWs — they are mapped from the MVS format to the CMS format by BSAM simulation. Any variance from these rules results in request cancellation.
- Given the difficulty of working with blocked data, especially for V and VB format datasets, it is generally a better idea to use WriteRecord than WriteBlock, and have the Dataset class handle the physical data formats.
- If there is no more room for a WriteBlock in a file, the dataset switches from the Open to the Full state. After this, a WriteRecord or WriteBlock results in request cancellation.
- If the value of NumberOfBuffers is greater than one, the writes are asynchronous, so WriteBuffer returns before the data has actually been written to disk. As such, it is possible that data written by a previous WriteBlock might not have actually been written to disk, either because of an I/O error or, more likely, because the file filled.