Read file as binary

Syntax

Read file as binary (refnum, binary-variable [,start-position] [,num-bytes]) Returns err-code

Description

Note: The flag is set according to whether Omnis was able to make a call to this external command.

This command reads a file, or part of a file, into a binary variable. You specify the file reference number returned by the Open file command in refnum. The binary data read from the file is returned in binary-variable.

If you specify the start-position, the file is read at that absolute byte position (0 is the first byte in the file, 1 is the second byte in the file, and so on), otherwise it begins at the current position (0 when the file is first opened). If you specify the number of num-bytes, only that many bytes are read, otherwise the file is read until the end of the file is reached.

If you specify a start-position of 0 and num-bytes equal to 0, the file pointer is reset to byte position 0 in the file. If a start-position of -1 is given, the file pointer is reset to the end of the file. For both cases an empty binary-variable buffer is returned.

It returns an error code (See Error Codes), or zero if no error occurs. Note the special case for end of file. In this case, the command returns the error code –39, but may still have read some data.

Example

# Prompt the user for a file and read its contents into the binary
# variable lBinfld 
Do  FileOps.$putfilename(lPathname,'Select a file','') Returns lReturnFlag
If  lReturnFlag
  Open file (lPathname,lRefNum)
  Read file as binary (lRefNum,lBinfld) Returns lErrCode
  Close file (lRefNum)
End If