ReadBlock (Dataset function) - Revision history

JAL: /* Usage notes */

2012-11-14T23:18:58Z

Usage notes

JAL2 at 22:10, 20 May 2011

2011-05-20T22:10:14Z

← Older revision		Revision as of 22:10, 20 May 2011
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>%dataset</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.

DmeWiccan: 1 revision

2011-05-20T18:03:36Z

1 revision

← Older revision	Revision as of 18:03, 20 May 2011
(No difference)

JAL2: Created page with "This function reads a block of data from an input `Dataset`. ==ReadBlock syntax==
%string = %dataset:ReadBlock
===Syntax terms===
2011-05-20T18:03:34Z
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..."

← Older revision Revision as of 18:03, 20 May 2011
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>.

==ReadBlock syntax==
==Syntax==

<p class="pre"> %string = %dataset:ReadBlock
{{Template:Dataset:ReadBlock syntax}}

</p>

===Syntax terms===
===Syntax terms===

<table class="syntaxTable">
<table class="syntaxTable">

Line 13: Line 14:

</td></tr></table>
</td></tr></table>

==Usage Notes==
==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}}

JAL2: Created page with "This function reads a block of data from an input `Dataset`. ==ReadBlock syntax==
%string = %dataset:ReadBlock
===Syntax terms===
2011-05-20T16:46:31Z
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..."
New page
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="syntaxTable">
<tr><th>%string</th>
<td>A longstring variable (though for small blocks, a regular string variable
might suffice) to receive the block of data.
</td></tr>
<tr><th>%dataset</th>
<td>A reference to an instance of a <var>Dataset</var> object.

</td></tr></table>
==Usage Notes==
<ul>
<li>The <var>Dataset</var> object must be an input object, that is, its
<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.
<li>The <var>Dataset</var> object must be in the <var>Open</var> 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
results in request cancellation.
<li>If a <var>ReadBlock</var> method is used after a
<var>[[ReadRecord (Dataset function)|ReadRecord]]</var>) method.
any records in
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>
processing for a single dataset.
<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>) property.
<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
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.
<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
<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
switches the dataset to the <var>AfterEnd</var> state.
After this, a <var>ReadRecord</var> or <var>ReadBlock</var> results in request cancellation.
<var>ReadBlock</var> will never return a null string except at end of file.
</ul>

← Older revision		Revision as of 23:18, 14 November 2012
Line 18:		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>) method.		<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>) property.		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 &~~amp;~~mdash; they are mapped to the MVS format by BSAM		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 43:		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}}

← Older revision		Revision as of 18:03, 20 May 2011
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>.
	==~~ReadBlock syntax~~==		==Syntax==
	~~<p class="pre"> %string = %dataset~~:ReadBlock		{{Template:Dataset:ReadBlock syntax}}
	~~</p>~~
	===Syntax terms===		===Syntax terms===
	<table class="syntaxTable">		<table class="syntaxTable">
Line 13:		Line 14:

	</td></tr></table>		</td></tr></table>
	==Usage ~~Notes~~==		==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}}