CsvFileInputRecordStream.ReadRecord

Syntax

CsvFileInputRecordStream.ReadRecord( record, mapping = "")

Return Value

Long

Returns 0 if a record was successfully read. Returns -1 if end of file was encountered before reading a record. Returns 1 if the end of a table was encountered before reading a record.

Purpose

Reads the next record from the stream. Implements InputRecordStream.ReadRecord .

Remarks

CsvFileInputRecordStream is designed to work with CSV files that contain multiple tables. Strictly speaking, such files are not compliant with RFC 4180, but many common spreadsheet applications support them regardless.

If CsvFileInputRecordStream.ReadRecord encounters an empty line or a line with nothing but separator characters, it returns 1 to indicate it has reached the end of the current table. CsvFileInputRecordStream.ReadRecord returns -1 to indicate it has reached the end of the underlying file.

Note CsvFileInputRecordStream considers only empty lines and lines that contain nothing but separators as end-of-table markers. Lines containing whitespaces are not interpreted as end of table. A record consisting of only empty strings can be represented by surrounding empty strings with quotes. Such a record is read normally and not interpreted as end of table.

Applications that only need to read the current table do not have to be aware of end-of-table vs. end-of-file distinction, as InputRecordStream.ReadRecord defines end of file to be any non-zero return value. However, applications that are aware they are reading a CsvFileInputRecordStream can distinguish between having reached the end of the current table and the actual end of the file by checking if the return value is +1 or -1 .

Note The TestStand For Each, Stream Loop, and Sweep Loop steps operate on the InputRecordStream interface. Loops terminate upon encountering either the end of the current table or the end of the file.

CsvFileInputRecordStream instances without record prototypes store data to fields in the order specified by the mapping parameter.

When the stream has a prototype, columns in the CSV file are mapped by name to fields in the record. As such, the record must be of a type that supports named fields: either a container or PropertyObject array. If the record is a container, the prototype field name determines the name of the subproperty the value in its column is stored to. If the record is an array, the prototype specifies the name of the array element(s) the value in its column is stored to. The record parameter cannot be a string or other type of array, as these types do not support named fields. Specifying a field mapping when a prototype is present results in a run-time error.

Parameters

record As PropertyObject

[In/Out] Specifies where to store the incoming record. Refer to InputRecordStream.ReadRecord for more information.

Note When a prototype is present, the record parameter must be either a container or an array of containers with named array elements. It cannot be another type of array or a string.

mapping As String

[In] [ Optional ] Specifies the mapping to elements (subproperties or array elements) in the record parameter from fields in the CSV file. Refer to InputRecordStream.ReadRecord for more information. Passing a non-empty field mapping to a stream that has a record prototype results in a run-time error.

See Also

InputRecordStream.ReadRecord

CsvFileInputRecordStream.SetRecordPrototype

CsvFileInputRecordStream.GetRecordPrototype

CsvFileInputRecordStream.ReadRecordPrototype