WriteRecord (Dataset subroutine): Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
mNo edit summary |
||
| (One intermediate revision by one other user not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Dataset:WriteRecord subtitle}} | {{Template:Dataset:WriteRecord subtitle}} | ||
==Syntax== | ==Syntax== | ||
{{Template:Dataset:WriteRecord syntax}} | {{Template:Dataset:WriteRecord syntax}} | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th> | <tr><th>dataset</th> | ||
<td>A | <td>A reference to an instance of a <var>Dataset</var> object.</td></tr> | ||
</td></tr> | |||
<tr><th> | <tr><th>string</th> | ||
<td>A | <td>A string or [[Longstrings|longstring]] variable that contains the records to be written.</td></tr> | ||
</table> | |||
</td></tr></table> | |||
==Usage notes== | ==Usage notes== | ||
<ul> | <ul> | ||
<li>To use the <var>WriteRecord</var> method, the <var>Dataset</var> object must be an output object, | <li>To use the <var>WriteRecord</var> method, the <var>Dataset</var> object must be an output object, | ||
that is, its [[Output (Dataset property)|Output]] | that is, its <var>[[Output (Dataset property)|Output]]</var> value must be <var>True</var>. | ||
Using <var>WriteRecord</var> against an input dataset results in request cancellation. | Using <var>WriteRecord</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>WriteRecord</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>WriteRecord</var> method. | |||
Using <var>WriteRecord</var> against a dataset in the <var>Closed</var> or <var>Full</var> state | Using <var>WriteRecord</var> against a dataset in the <var>Closed</var> or <var>Full</var> state | ||
results in request cancellation. | results in request cancellation. | ||
<li>If a <var>WriteRecord</var> method is used after a <var>WriteRecord</var> method, the block | <li>If a <var>WriteRecord</var> method is used after a <var>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>For F and FB format files, the output string written by <var>WriteRecord</var> | <li>For F and FB format files, the output string written by <var>WriteRecord</var> | ||
must be shorter than or equal in length to the value of <var>[[RecordLength (Dataset property)|RecordLength]]</var> | must be shorter than or equal in length to the value of <var>[[RecordLength (Dataset property)|RecordLength]]</var>. | ||
Records shorter than the <var>RecordLength</var> value are padded with blanks so their | Records shorter than the <var>RecordLength</var> value are padded with blanks so their | ||
length exactly equals the <var>RecordLength</var>. | length exactly equals the <var>RecordLength</var>. Output strings that are too long result in request cancellation. | ||
Output strings that are too long result in request cancellation. | |||
<li>For V and VB format files, the output string written by <var>WriteRecord</var> | <li>For V and VB format files, the output string written by <var>WriteRecord</var> | ||
must be shorter than or equal in length to the <var>RecordLength</var> value minus four. | must be shorter than or equal in length to the <var>RecordLength</var> value minus four. | ||
Four is subtracted because the <var>WriteRecord</var> method adds the required RDW before | Four is subtracted because the <var>WriteRecord</var> method adds the required RDW before the record. | ||
the record. | |||
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. | |||
Output strings that are too long result in request cancellation. | Output strings that are too long result in request cancellation. | ||
<li>If there is no more room for a <var>WriteRecord</var> in a file, the dataset switches | <li>If there is no more room for a <var>WriteRecord</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 (Dataset subroutine)|WriteBlock]]</var> results in request cancellation. | ||
<li>Since <var>WriteRecord</var> blocks the data before writing it, <var>WriteRecord</var> usually | <li>Since <var>WriteRecord</var> blocks the data before writing it, <var>WriteRecord</var> usually | ||
returns before the data has actually been written to disk. | returns before the data has actually been written to disk. | ||
| Line 45: | Line 47: | ||
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. | ||
==See also== | ==See also== | ||
{{Template:Dataset:WriteRecord footer}} | {{Template:Dataset:WriteRecord footer}} | ||
Latest revision as of 00:41, 15 November 2012
Write a record to this dataset (Dataset class)
Syntax
dataset:WriteRecord( string) Throws WriteError
Syntax terms
| dataset | A reference to an instance of a Dataset object. |
|---|---|
| string | A string or longstring variable that contains the records to be written. |
Usage notes
- To use the WriteRecord method, the Dataset object must be an output object, that is, its Output value must be True. Using WriteRecord against an input dataset results in request cancellation.
- The Dataset object must be in the Open state to use the WriteRecord method. Using WriteRecord against a dataset in the Closed or Full state results in request cancellation.
- If a WriteRecord 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.
- For F and FB format files, the output string written by WriteRecord must be shorter than or equal in length to the value of RecordLength. Records shorter than the RecordLength value are padded with blanks so their length exactly equals the RecordLength. Output strings that are too long result in request cancellation.
- For V and VB format files, the output string written by WriteRecord must be shorter than or equal in length to the RecordLength value minus four. Four is subtracted because the WriteRecord method adds the required RDW before the record. 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. Output strings that are too long result in request cancellation.
- If there is no more room for a WriteRecord in a file, the dataset switches from the Open to the Full state. After this, a WriteRecord or WriteBlock results in request cancellation.
- Since WriteRecord blocks the data before writing it, WriteRecord usually
returns before the data has actually been written to disk.
As such, it is possible that data written by a previous WriteRecord might
not have actually been written to disk, either because of an I/O error or,
more likely, because the file filled.
See also