base.Channel.read

Reads a list of data delimited by a separator from the channel.

Syntax

Note: In the next(s) syntax diagram(s), the [ ] { } | symbols are part of the syntax.

read( variableList )
  RETURNS INTEGER

where variableList can be one of:

```
variable
```
```
[ variable , ... ]
```
```
record
```
```
[ record.* ]
```

variable is a program variable of a primitive data type such as INTEGER, VARCHAR(50), etc.
record is a variable defined as a RECORD.
When there are multiple variables to read, the variable(s) must be specified between [ ] square brackets. These are provided as a variable parameter list.
If only one variables is to be read, you can specify the variable without the [ ] brackets.
To read all values into a RECORD variable, the record.* notation can be used when surrounded by [ ] brackets. Or, you can also directly specify the record name without the .* notation and no [ ] brackets.

Usage

After opening the channel object, use the read() method to read a record of data from the channel.

The read() method uses the field delimiter defined by setDelimiter(). The delimiter also defines deserialization rules for example when using "CSV".

The read() method takes a modifiable list of variables as parameter.

A call to read() is blocking until the read operation is complete.

If the read() method returns less data than expected, then the remaining variables will be initialized to NULL. If the read() method returns more data than expected, the data is silently ignored.

Any target variable must have a primitive type, or be a RECORD that contains only members defined with a primitive type.

If data is read, the read() method returns TRUE. Otherwise, it returns FALSE, indicating the end of the file or stream.

Important:

Files encoded in UTF-8 can start with the UTF-8 Byte Order Mark (BOM), a sequence of 0xEF 0xBB 0xBF bytes, also known as UNICODE U+FEFF. When reading files, Genero BDL will ignore the UTF-8 BOM, if it is present at the beginning of the file. This applies to instructions such as LOAD, as well as I/O APIs such as base.Channel.read() and readLine().

Example

DEFINE cust_rec RECORD LIKE customer.*
...
WHILE ch.read(cust_rec) -- equivalent to: ch.read([cust_rec.*])
  ...
END WHILE

For a complete example, see Example 1: Using record-formatted data file.