ReadBlock (Dataset function): Difference between revisions
Jump to navigation
Jump to search
m (Created page with "This function reads a block of data from an input <var>Dataset</var>. ==ReadBlock syntax== <p class="pre"> %string = %dataset:ReadBlock </p> ===Syntax terms=== <table class="synt...") |
m (Created page with "This function reads a block of data from an input <var>Dataset</var>. ==ReadBlock syntax== <p class="pre"> %string = %dataset:ReadBlock </p> ===Syntax terms=== <table class="synt...") |
||
| Line 1: | Line 1: | ||
{{Template:Dataset:ReadBlock subtitle}} | |||
This function reads a block of data from an input <var>Dataset</var>. | This function reads a block of data from an input <var>Dataset</var>. | ||
== | ==Syntax== | ||
{{Template:Dataset:ReadBlock syntax}} | |||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
| Line 13: | Line 14: | ||
</td></tr></table> | </td></tr></table> | ||
==Usage | ==Usage notes== | ||
<ul> | <ul> | ||
<li>The <var>Dataset</var> object must be an input object, that is, its | <li>The <var>Dataset</var> object must be an input object, that is, its | ||
| Line 33: | Line 34: | ||
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 — they are mapped to the MVS format by BSAM | with BDWs and RDWs &mdash; 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 | ||
| Line 43: | Line 44: | ||
<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== | |||
{{Template:Dataset:ReadBlock footer}} | |||
Revision as of 18:03, 20 May 2011
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 RecordLength) property.
- 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.