WriteBlock (Dataset subroutine) - Revision history

JAL: /* Usage notes */

2012-11-15T00:45:21Z

Usage notes

← Older revision		Revision as of 00:45, 15 November 2012
Line 28:		Line 28:

	<li>The block written by <var>WriteBlock</var> must conform to the output file's format.		<li>The block written by <var>WriteBlock</var> must conform to the output file's format.
	That is, its length must be less than or equal to the		That is, its length must be less than or equal to the <var>[[BlockSize (Dataset property)\|BlockSize]]</var> value.
	<var>[[BlockSize (Dataset property)\|BlockSize]]</var>.		For F format files, its length must be an exact multiple of the <var>[[RecordLength (Dataset property)\|RecordLength]]</var> value.
	For F format files, its length must be an exact multiple of the		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
	<var>[[RecordLength (Dataset property)\|RecordLength]]</var> 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).		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 from the MVS format to the		with BDWs and RDWs — they are mapped from the MVS format to the CMS format by BSAM simulation.
	CMS format by BSAM simulation.
	Any variance from these rules results in request cancellation.		Any variance from these rules results in request cancellation.

Line 49:		Line 45:

	<li>If the value of <var>[[NumberOfBuffers (Dataset property)\|NumberOfBuffers]]</var>		<li>If the value of <var>[[NumberOfBuffers (Dataset property)\|NumberOfBuffers]]</var>
	is greater than one, the writes are asynchronous,		is greater than one, the writes are asynchronous, so <var>WriteBuffer</var> returns before the data has actually been written to disk.
	so <var>WriteBuffer</var> returns before the data has actually been written to disk.
	As such, it is possible that data written by a previous <var>WriteBlock</var> might		As such, it is possible that data written by a previous <var>WriteBlock</var> might
	not have actually been written to disk, either because of an I/O error or, more likely, because the file filled.		not have actually been written to disk, either because of an I/O error or, more likely, because the file filled.

JAL at 00:27, 15 November 2012

2012-11-15T00:27:31Z

← Older revision		Revision as of 00:27, 15 November 2012
Line 3:		Line 3:
	==Syntax==		==Syntax==
	{{Template:Dataset:WriteBlock syntax}}		{{Template:Dataset:WriteBlock syntax}}

	===Syntax terms===		===Syntax terms===
	<table class="syntaxTable">		<table class="syntaxTable">
	<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. </td></tr>
	</td></tr>
	<tr><th>string</th>		<tr><th>string</th>
	<td>A [[Longstrings\|longstring]] variable (though for small blocks, a regular string variable might suffice) that contains the block of data to be written.		<td>A [[Longstrings\|longstring]] variable (though for small blocks, a regular string variable might suffice) that contains the block of data to be written.
Line 15:		Line 16:
	==Usage notes==		==Usage notes==
	<ul>		<ul>
	<li>To use the <var>WriteBlock</var> method, the Dataset object must be an output object,		<li>To use the <var>WriteBlock</var> method, the <var>Dataset</var> object must be an output object,
	that is, its <var>[[Output (Dataset property)\|Output]]</var> property must be <var>True</var>.		that is, its <var>[[Output (Dataset property)\|Output]]</var> property value must be <var>True</var>.
	Using <var>WriteBlock</var> against an input dataset results in request cancellation.		Using <var>WriteBlock</var> against an input dataset results in request cancellation.
	<li>The <var>Dataset</var> object must be in the <var>Open</var> state to use the <var>WriteBlock</var> method.
	Using <var>WriteBlock</var> against a dataset in the <var>Closed</var> or <var>Full</var> state		<li>The <var>Dataset</var> object must be in the <var>Open</var> [[Dataset class#The DatasetState enumeration\|state]] to use the <var>WriteBlock</var> method.
	results in request cancellation.		Using <var>WriteBlock</var> against a dataset in the <var>Closed</var> or <var>Full</var> state results in request cancellation.
	<li>If a <var>WriteBlock</var> method is used after a <var>WriteRecord</var> method, the block
			<li>If a <var>WriteBlock</var> method is used after a <var>[[WriteRecord (Dataset subroutine)\|WriteRecord]]</var> method, the block
	containing the record written by the preceding <var>WriteRecord</var> is written,		containing the record written by the preceding <var>WriteRecord</var> is written,
	if it has not already been written.		if it has not already been written.

	<li>The block written by <var>WriteBlock</var> must conform to the output file's format.		<li>The block written by <var>WriteBlock</var> must conform to the output file's format.
	That is, its length must be less than or equal to the		That is, its length must be less than or equal to the
Line 36:		Line 39:
	CMS format by BSAM simulation.		CMS format by BSAM simulation.
	Any variance from these rules results in request cancellation.		Any variance from these rules results in request cancellation.

	<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>WriteRecord</var> than		VB format datasets, it is generally a better idea to use <var>WriteRecord</var> than
	<var>WriteBlock</var>, and have the <var>Dataset</var> class handle the physical data formats.		<var>WriteBlock</var>, and have the <var>Dataset</var> class handle the physical data formats.

	<li>If there is no more room for a <var>WriteBlock</var> in a file, the dataset switches		<li>If there is no more room for a <var>WriteBlock</var> in a file, the dataset switches
	from the <var>Open</var> to the <var>Full</var> state.		from the <var>Open</var> to the <var>Full</var> state.
	After this, a <var>WriteRecord</var> or <var>WriteBlock</var> results in request cancellation.		After this, a <var>WriteRecord</var> or <var>WriteBlock</var> results in request cancellation.
	<li>If the value of [[NumberOfBuffers (Dataset property)\|NumberOfBuffers]]
			<li>If the value of <var>[[NumberOfBuffers (Dataset property)\|NumberOfBuffers]]</var>
	is greater than one, the writes are asynchronous,		is greater than one, the writes are asynchronous,
	so <var>WriteBuffer</var> returns before the data has actually been written to disk.		so <var>WriteBuffer</var> returns before the data has actually been written to disk.
	As such, it is possible that data written by a previous <var>WriteBlock</var> might		As such, it is possible that data written by a previous <var>WriteBlock</var> might
	not have actually been written to disk, either because of an I/O error or,		not have actually been written to disk, either because of an I/O error or, more likely, because the file filled.
	more likely, because the file filled.
	</ul>		</ul>

	==See also==		==See also==
	{{Template:Dataset:WriteBlock footer}}		{{Template:Dataset:WriteBlock footer}}

JAL2 at 22:37, 20 May 2011

2011-05-20T22:37:56Z

← Older revision		Revision as of 22:37, 20 May 2011
Line 1:		Line 1:
	{{Template:Dataset:WriteBlock subtitle}}		{{Template:Dataset:WriteBlock subtitle}}

	~~This subroutine writes a block of data to an output dataset.~~
	==Syntax==		==Syntax==
	{{Template:Dataset:WriteBlock syntax}}		{{Template:Dataset:WriteBlock syntax}}
	===Syntax terms===		===Syntax terms===
	<table class="syntaxTable">		<table class="syntaxTable">
	<tr><th>~~%string~~</th>		<tr><th>dataset</th>
	<td>A ~~[[Longstrings\|longstring]] variable (though for small blocks,~~ a ~~regular string variable~~		<td>A reference to an instance of a <var>Dataset</var> object.
	~~might suffice) that contains the block of data to be written~~.
	</td></tr>		</td></tr>
	<tr><th>~~%dataset~~</th>		<tr><th>string</th>
	<td>A ~~reference~~ to ~~an instance of a <var>Dataset</var> object~~.		<td>A [[Longstrings\|longstring]] variable (though for small blocks, a regular string variable might suffice) that contains the block of data to be written.
			</td></tr>
	</td></tr></table>		</table>

	==Usage notes==		==Usage notes==
	<ul>		<ul>

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 subroutine writes a block of data to an output dataset. ==WriteBlock syntax==
%dataset:writeBlock(%string)
===Syntax terms===
2011-05-20T18:03:34Z
Created page with "This subroutine writes a block of data to an output dataset. ==WriteBlock syntax== <p class="pre"> %dataset:writeBlock(%string) </p> ===Syntax terms=== <table class="syntaxTable"..."

← Older revision Revision as of 18:03, 20 May 2011
Line 1: Line 1:

{{Template:Dataset:WriteBlock subtitle}}

This subroutine writes a block of data to an output dataset.
This subroutine writes a block of data to an output dataset.

==WriteBlock syntax==
==Syntax==

<p class="pre"> %dataset:writeBlock(%string)
{{Template:Dataset:WriteBlock 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>To use the <var>WriteBlock</var> method, the Dataset object must be an output object,
<li>To use the <var>WriteBlock</var> method, the Dataset object must be an output object,

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 from the MVS format to the
with BDWs and RDWs &mdash; they are mapped from the MVS format to the

CMS format by BSAM simulation.
CMS format by BSAM simulation.

Any variance from these rules results in request cancellation.
Any variance from these rules results in request cancellation.

Line 49: Line 50:

more likely, because the file filled.
more likely, because the file filled.

</ul>
</ul>

==See also==

{{Template:Dataset:WriteBlock footer}}

JAL2: Created page with "This subroutine writes a block of data to an output dataset. ==WriteBlock syntax==
%dataset:writeBlock(%string)
===Syntax terms===
2011-05-20T16:53:31Z
Created page with "This subroutine writes a block of data to an output dataset. ==WriteBlock syntax== <p class="pre"> %dataset:writeBlock(%string) </p> ===Syntax terms=== <table class="syntaxTable"..."
New page
This subroutine writes a block of data to an output dataset.
==WriteBlock syntax==
<p class="pre"> %dataset:writeBlock(%string)
</p>
===Syntax terms===
<table class="syntaxTable">
<tr><th>%string</th>
<td>A [[Longstrings|longstring]] variable (though for small blocks, a regular string variable
might suffice) that contains the block of data to be written.
</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>To use the <var>WriteBlock</var> method, the Dataset object must be an output object,
that is, its <var>[[Output (Dataset property)|Output]]</var> property must be <var>True</var>.
Using <var>WriteBlock</var> against an input dataset results in request cancellation.
<li>The <var>Dataset</var> object must be in the <var>Open</var> state to use the <var>WriteBlock</var> method.
Using <var>WriteBlock</var> against a dataset in the <var>Closed</var> or <var>Full</var> state
results in request cancellation.
<li>If a <var>WriteBlock</var> method is used after a <var>WriteRecord</var> method, the block
containing the record written by the preceding <var>WriteRecord</var> is written,
if it has not already been written.
<li>The block written by <var>WriteBlock</var> must conform to the output file's format.
That is, its length must be less than or equal to the
<var>[[BlockSize (Dataset property)|BlockSize]]</var>.
For F format files, its length must be an exact multiple of the
<var>[[RecordLength (Dataset property)|RecordLength]]</var> 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.
<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>WriteRecord</var> than
<var>WriteBlock</var>, and have the <var>Dataset</var> class handle the physical data formats.
<li>If there is no more room for a <var>WriteBlock</var> in a file, the dataset switches
from the <var>Open</var> to the <var>Full</var> state.
After this, a <var>WriteRecord</var> or <var>WriteBlock</var> results in request cancellation.
<li>If the value of [[NumberOfBuffers (Dataset property)|NumberOfBuffers]]
is greater than one, the writes are asynchronous,
so <var>WriteBuffer</var> returns before the data has actually been written to disk.
As such, it is possible that data written by a previous <var>WriteBlock</var> might
not have actually been written to disk, either because of an I/O error or,
more likely, because the file filled.
</ul>