file.read

Syntax

i = file.read(a,i<,p><,i1><,i2>)

Read the contents of a file. Either the most recently opened file is read, or a file is specified with a file pointer returned from file.open.pointer. The following modes are supported:

  • If two arguments are given, the first argument must be an array pointer. In this case, the most recently opened file is read.
  • If three arguments are given, the first argument must be an array pointer and the third argument must be a file pointer. In this case, the specified file is read.
  • If four or five arguments are given, then they must follow the pattern 1) string specifying the file name, 2) integer specifying the mode (FISH = 0, ASCII = 1, or binary = 2), 3) array pointer, 4) integer indicating the number of records to read, and 5) optional position (in bytes) to start reading.
Returns:

i - Read status with the following values:

  • 0: requested number of records were read without error
  • -1: error on read (except end-of-file)
  • n: positive value indicates that end-of-file was encountered after reading n lines
Arguments:

a - Array pointer or string.

  • If two or three arguments are provided, the first argument must be an array pointer. The array is filled with the read content.
  • If four or five arguments are provided, the first argument is a string specifying the file name.

i - Number of records to read if two arguments are given, or mode (FISH = 0, ASCII = 1, or binary = 2) if four or five arguments are given. Each record is either a line of ASCII/binary data, or a single FISH variable if in FISH mode.

p - File pointer or array pointer. If three arguments are given, this argument must be a file pointer. If four or five arguments are given, this is an array pointer to be filled with the read data.

i1 - Number of records to read. This is used when the first argument is the file name.

i2 - Optional position, in bytes, to start reading the file.

Example

model new
model largestrain off
fish define setup
    global a_size = 20
    global IO_READ  = 0
    global IO_WRITE = 1
    global IO_FISH  = 0
    global IO_ASCII = 1
    global filename = 'junk.dat'
end
@setup
;
fish define io
    array aa(a_size) bb(a_size)
    ;  
    ; ASCII I/O TEST ------------------
    local status = file.open(filename, IO_WRITE, IO_ASCII)
    aa(1)  = 'Line 1 ... Fred'
    aa(2)  = 'Line 2 ... Joe'
    aa(3)  = 'Line 3 ... Roger'
    status = file.write(aa,3)
    status = file.close
    status = file.open(filename, IO_READ, IO_ASCII)
    status = file.read(bb, a_size)
    if status # 3 then
        local oo = io.out(' Bad number of lines')
    endif
    status = file.close
    ;  
    ; now check results...
    loop local n (1,3)
        if string.token(bb(n), 2) # n then
            oo = io.out(' Bad 2nd item in loop ' + string(n))
            exit
        endif
    endloop
    ;  
    if string.token.type(bb(3),4) # 3 then
        oo = io.out(' Not a string')
        exit
    endif
    ;  
    ; FISH I/O TEST -----------------
    status = file.open(filename, IO_WRITE, IO_FISH)
    local funny_int   = 1234567
    local funny_float = 1.2345e6
    aa(1)  = '---> All tests passed OK'
    aa(2)  = funny_int
    aa(3)  = funny_float
    ;  
    status = file.write(aa,3)
    status = file.close
    status = file.open(filename, IO_READ, IO_FISH)
    status = file.read(bb, 3)
    status = file.close
    ;  
    ; now check results...
    if type(bb(1)) # 3 then
        oo = io.out(' Bad FISH string read/write')
        exit
    endif
    if bb(2) # funny_int then
        oo = io.out(' Bad FISH integer read/write')
        exit
    endif
    if bb(3) # funny_float then
        oo = io.out(' Bad FISH float read/write')
        exit
    endif
    oo = io.out(bb(1)) ; (should be a good message)
    command
        sys "del junk.dat"
    endcommand
end
;
@io