ReadBlock (Dataset function): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (→Usage notes) |
||
| (One intermediate revision by one other user not shown) | |||
| Line 7: | Line 7: | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%string</th> | <tr><th>%string</th> | ||
<td>A longstring variable (though for small blocks, a regular string variable | <td>A [[Longstrings|longstring]] variable (though for small blocks, a regular string variable might suffice) to receive the block of data. | ||
might suffice) to receive the block of data. | |||
</td></tr> | </td></tr> | ||
<tr><th> | <tr><th>dataset</th> | ||
<td>A reference to an instance of a <var>Dataset</var> object. | <td>A reference to an instance of a <var>Dataset</var> object. | ||
| Line 19: | Line 18: | ||
<var>[[Output (Dataset property)|Output]]</var> property must be <var>False</var>, to use the <var>ReadBlock</var> method. | <var>[[Output (Dataset property)|Output]]</var> property must be <var>False</var>, to use the <var>ReadBlock</var> method. | ||
Using <var>ReadBlock</var> against an output dataset results in request cancellation. | Using <var>ReadBlock</var> against an output dataset results in request cancellation. | ||
<li>The <var>Dataset</var> object must be in the <var>Open</var> state to use the <var>ReadBlock</var> method. | |||
<li>The <var>Dataset</var> object must be in the <var>Open</var> [[Dataset class#The DatasetState enumeration|state]] to use the <var>ReadBlock</var> method. | |||
Using <var>ReadBlock</var> against a <var>Dataset</var> in the <var>Closed</var> or <var>AfterEnd</var> state | Using <var>ReadBlock</var> against a <var>Dataset</var> in the <var>Closed</var> or <var>AfterEnd</var> state | ||
results in request cancellation. | results in request cancellation. | ||
<li>If a <var>ReadBlock</var> method is used after a | |||
<var>[[ReadRecord (Dataset function)|ReadRecord]]</var> | <li>If a <var>ReadBlock</var> method is used after a <var>[[ReadRecord (Dataset function)|ReadRecord]]</var> method. | ||
any records in | any records in the block after the record returned by the preceding <var>ReadRecord</var> are skipped. | ||
the block after the record returned by the preceding <var>ReadRecord</var> are skipped. | |||
As such, it is generally not a good idea to mix <var>ReadBlock</var> and <var>ReadRecord</var> | As such, it is generally not a good idea to mix <var>ReadBlock</var> and <var>ReadRecord</var> | ||
processing for a single dataset. | processing for a single dataset. | ||
<li>For F or FB files, the string returned by <var>ReadBlock</var> has a length that | <li>For F or FB files, the string returned by <var>ReadBlock</var> has a length that | ||
is an exact multiple of <var>[[RecordLength (Dataset property)|RecordLength]]</var> | is an exact multiple of the <var>[[RecordLength (Dataset property)|RecordLength]]</var> property value. | ||
<li>For V or VB files, the string returned by <var>ReadBlock</var> has a binary BDW | <li>For V or VB files, the string returned by <var>ReadBlock</var> has a binary BDW | ||
(Block Descriptor Word), and the individual records will be preceded by | (Block Descriptor Word), and the individual records will be preceded by a binary RDW (Record Descriptor Word). | ||
a binary RDW (Record Descriptor Word). | |||
This is true even under CMS, where records are not really stored on disks | This is true even under CMS, where records are not really stored on disks | ||
with BDWs and RDWs & | with BDWs and RDWs — they are mapped to the MVS format by BSAM | ||
simulation. | simulation. | ||
<li>Given the difficulty of working with blocked data, especially for V and | <li>Given the difficulty of working with blocked data, especially for V and | ||
VB format datasets, it is generally a better idea to use <var>ReadRecord</var> than | VB format datasets, it is generally a better idea to use <var>ReadRecord</var> than | ||
<var>ReadBlock</var>, and have the <var>Dataset</var> class handle the physical data formats. | <var>ReadBlock</var>, and have the <var>Dataset</var> class handle the physical data formats. | ||
<li>When a <var>ReadBlock</var> reaches the end of a file, it returns a null string and | <li>When a <var>ReadBlock</var> reaches the end of a file, it returns a null string and | ||
switches the dataset to the <var>AfterEnd</var> state. | switches the dataset to the <var>AfterEnd</var> state. | ||
| Line 44: | Line 46: | ||
<var>ReadBlock</var> will never return a null string except at end of file. | <var>ReadBlock</var> will never return a null string except at end of file. | ||
</ul> | </ul> | ||
==See also== | ==See also== | ||
{{Template:Dataset:ReadBlock footer}} | {{Template:Dataset:ReadBlock footer}} | ||
Latest revision as of 23:18, 14 November 2012
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.