ReadRecord (Dataset function): Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
m (→Usage notes) |
||
| Line 17: | Line 17: | ||
<var>[[Output (Dataset property)|Output]]</var> property must be <var>False</var> to use the <var>ReadRecord</var> method. | <var>[[Output (Dataset property)|Output]]</var> property must be <var>False</var> to use the <var>ReadRecord</var> method. | ||
Using <var>ReadRecord</var> against an output dataset results in request cancellation. | Using <var>ReadRecord</var> against an output dataset results in request cancellation. | ||
<li>The <var>Dataset</var> object must be in the <var>Open</var> <var> | |||
<li>The <var>Dataset</var> object must be in the <var>Open</var> [[Dataset class#The DatasetState enumeration|state]] to use the <var>ReadRecord</var> method. | |||
Using <var>ReadRecord</var> against a dataset in the <var>Closed</var> or <var>AfterEnd</var> state | Using <var>ReadRecord</var> against a dataset in the <var>Closed</var> or <var>AfterEnd</var> state | ||
results in request cancellation. | results in request cancellation. | ||
<li>If a <var>ReadRecord</var> method is used after a <var>ReadBlock</var> method, the first record | <li>If a <var>ReadRecord</var> method is used after a <var>ReadBlock</var> method, the first record | ||
in the block after the block returned by the <var>ReadBlock</var> is returned. | in the block after the block returned by the <var>ReadBlock</var> is returned. | ||
<li>For F or FB files, the string returned by <var>ReadRecord</var> has a length that | <li>For F or FB files, the string returned by <var>ReadRecord</var> has a length that | ||
is exactly equal to the <var>RecordLength</var>. | is exactly equal to the <var>RecordLength</var>. | ||
<li>For V or VB files, the string returned by <var>ReadRecord</var> has a length less | <li>For V or VB files, the string returned by <var>ReadRecord</var> has a length less | ||
than the <var>[[RecordLength (Dataset property)|RecordLength]]</var> property. | than the <var>[[RecordLength (Dataset property)|RecordLength]]</var> property value. | ||
It does '''not''' contain the record's RDW, that is, it only contains the | It does '''not''' contain the record's RDW, that is, it only contains the | ||
data portion of the record. | data portion of the record. | ||
| Line 31: | Line 35: | ||
modification (except for, perhaps, record padding issues) for different | modification (except for, perhaps, record padding issues) for different | ||
<var>RecordFormats</var>. | <var>RecordFormats</var>. | ||
<li>When a <var>ReadRecord</var> reaches the end of a file, it returns a null string and | <li>When a <var>ReadRecord</var> reaches the end of a file, it returns a null string and | ||
switches the dataset to the <var>AfterEnd</var> state. | switches the dataset to the <var>AfterEnd</var> state. | ||
| Line 40: | Line 45: | ||
record to determine if the end of file has been reached. | record to determine if the end of file has been reached. | ||
</ul> | </ul> | ||
==See also== | ==See also== | ||
{{Template:Dataset:ReadRecord footer}} | {{Template:Dataset:ReadRecord footer}} | ||
Revision as of 23:22, 14 November 2012
Read a record from this dataset (Dataset class)
Syntax
%string = dataset:ReadRecord
Syntax terms
| %string | A string or longstring variable to receive the block of data. |
|---|---|
| dataset | A reference to an instance of a Dataset object. |
Usage notes
- The Dataset object must be an input object, that is, its Output property must be False to use the ReadRecord method. Using ReadRecord against an output dataset results in request cancellation.
- The Dataset object must be in the Open state to use the ReadRecord method. Using ReadRecord against a dataset in the Closed or AfterEnd state results in request cancellation.
- If a ReadRecord method is used after a ReadBlock method, the first record in the block after the block returned by the ReadBlock is returned.
- For F or FB files, the string returned by ReadRecord has a length that is exactly equal to the RecordLength.
- For V or VB files, the string returned by ReadRecord has a length less than the RecordLength property value. It does not contain the record's RDW, that is, it only contains the data portion of the record. As such, a program that uses ReadRecord can generally be used without modification (except for, perhaps, record padding issues) for different RecordFormats.
- When a ReadRecord reaches the end of a file, it returns a null string and switches the dataset to the AfterEnd state. After this, a ReadRecord or ReadBlock results in request cancellation. For V or VB datasets, it is possible for ReadRecord to return a null record when it is not at the end of file. Because of this, it is probably best to check the Dataset's State property rather than using the size of the returned record to determine if the end of file has been reached.