WriteBlock (Dataset subroutine): Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
m (→Usage notes) |
||
| (One intermediate revision by the same user not shown) | |||
| 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 <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. | ||
<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]] | |||
is greater than one, the writes are asynchronous, | <li>If the value of <var>[[NumberOfBuffers (Dataset property)|NumberOfBuffers]]</var> | ||
so <var>WriteBuffer</var> returns before the data has actually been written to disk. | 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 | 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}} | ||
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.