WriteBlock (Dataset subroutine): Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
m (→Usage notes) |
||
| 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 & | 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. | ||
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.