New in version 6.3.0: See the new features.

Read from a sequential file

fread

Read data from a sequential file, socket or pipe


SYNTAX

fread file_handle field_or_record_id [, field_or_record_id]… \
[err = label] [to = timeout[:label]] [traps = label]

Reads binary data from the sequential file, socket or pipe which is open on the specified file_handle into the listed records and fields. The total number of bytes read will equal the sum of sizes of the fields and records supplied.

file_handle

It can be the handle returned by the fopen command (it returns a negative number to differentitate the #channel case) or an integer in the range 1-64 specifying the number of the channel on which the sequential file, socket or pipe (opened by the open # command) is open. It may be a constant, field name or expression.

field_or_record_id

Each field specified must be the name of a field in a Sculptor keyed file, !record field or of a temporary field declared in the program. The fields may be of any type.

Likewise the record can be a !record or a ![o]file declared in the program. Including record arrays and nested records.

The data is read as binary directly into the supplied field or record. The size of the data read from the file is equal to the field or record size.

[err = label]

Errors return the trappable condition err, which may be trapped by the err = clause or by the general traps = clause. The error number is stored in the system variable sys.Error , and control passes to the line indicated by label. The error numbers are defined by manifest constants in the file errors.h, which is located in the Sculptor include directory. This file may be included in a program by means of an !include declaration. The possible errors are:

No

Manifest constant

Meaning

1

BAD_CHANNEL

file_handle is wrong

9

FGETERR

read error, check errno

12

TIMEOUT_EXCEEDED

timeout exceeded

14

BAD_ARGS

bad/wrong number of arguments

If an error occurs and is not trapped, an error message is displayed and control passes to the active menu, if any. If no menu is active the program exits.

[to = timeout[:label]]

Defines the timeout value and if the label is defined then control passes to the line indicated by label, in case the timeout is reached.

If this condition is not trapped, the error timeout exceeded is displayed and control passes to the active menu, if any. If no menu is active the program exits.

[traps = label]

General purpose trap clause that traps any condition not explicitly trapped, passing control to the line indicated by label. It has the lowest priority, and is only invoked if a trappable condition has not been more explicitly trapped.


NOTES

  • If the handle/channel is already closed the command is ignored.


EXAMPLE

This example shows a field and record read:

!temp fHandle,,i2
!temp magic,,i4

!record dataRec {
  Name,,a32,,v
  Surname,,a32,,v
  Age,,u2
}

fopen fHandle "seqfile" "r"

fread fHandle magic

/* Read the person information if the magic number is correct */
if (magic == MAGIC_NUMBER) {
  fread fHandle dataRec
}

RELATED TOPICS

fwrite

fgets

fputs

fopen

fclose

get[field] #

put[field] #

Sequential files

Fcmds

Traps