ReadBlock (Dataset function)
Read data from this dataset (Dataset class)
This function reads a block of data from an input Dataset.
Syntax
%string = dataset:ReadBlock
Syntax terms
| %string | A longstring variable (though for small blocks, a regular string variable might suffice) to receive the block of data. |
|---|---|
| dataset | A reference to an instance of a Dataset object. |
Usage notes
- The Dataset object must be an input object, that is, its Output property must be False, to use the ReadBlock method. Using ReadBlock against an output dataset results in request cancellation.
- The Dataset object must be in the Open state to use the ReadBlock method. Using ReadBlock against a Dataset in the Closed or AfterEnd state results in request cancellation.
- If a ReadBlock method is used after a ReadRecord method. any records in the block after the record returned by the preceding ReadRecord are skipped. As such, it is generally not a good idea to mix ReadBlock and ReadRecord processing for a single dataset.
- For F or FB files, the string returned by ReadBlock has a length that is an exact multiple of the RecordLength property value.
- For V or VB files, the string returned by ReadBlock has a binary BDW (Block Descriptor Word), and the individual records will 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 to the MVS format by BSAM simulation.
- Given the difficulty of working with blocked data, especially for V and VB format datasets, it is generally a better idea to use ReadRecord than ReadBlock, and have the Dataset class handle the physical data formats.
- When a ReadBlock reaches the end of a file, it returns a null string and switches the dataset to the AfterEnd state. After this, a ReadRecord or ReadBlock results in request cancellation. ReadBlock will never return a null string except at end of file.