WriteBlock (Dataset subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
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 &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 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.

Latest revision as of 00:45, 15 November 2012

Write a block of data to this dataset (Dataset class)


Syntax

dataset:WriteBlock( string) Throws WriteError

Syntax terms

dataset A reference to an instance of a Dataset object.
string A longstring variable (though for small blocks, a regular string variable might suffice) that contains the block of data to be written.

Usage notes

  • To use the WriteBlock method, the Dataset object must be an output object, that is, its Output property value must be True. Using WriteBlock against an input dataset results in request cancellation.
  • The Dataset object must be in the Open state to use the WriteBlock method. Using WriteBlock against a dataset in the Closed or Full state results in request cancellation.
  • If a WriteBlock method is used after a WriteRecord method, the block containing the record written by the preceding WriteRecord is written, if it has not already been written.
  • The block written by WriteBlock must conform to the output file's format. That is, its length must be less than or equal to the BlockSize value. For F format files, its length must be an exact multiple of the RecordLength 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.
  • Given the difficulty of working with blocked data, especially for V and VB format datasets, it is generally a better idea to use WriteRecord than WriteBlock, and have the Dataset class handle the physical data formats.
  • If there is no more room for a WriteBlock in a file, the dataset switches from the Open to the Full state. After this, a WriteRecord or WriteBlock results in request cancellation.
  • If the value of NumberOfBuffers is greater than one, the writes are asynchronous, so WriteBuffer returns before the data has actually been written to disk. As such, it is possible that data written by a previous WriteBlock might not have actually been written to disk, either because of an I/O error or, more likely, because the file filled.

See also