Read file as character

Syntax

Read file as character (refnum, character-variable [,start-position] [,num-characters]) 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 character variable. You specify the file reference number returned by the Open file command in refnum. The text read from the file is returned in character-variable.

If you specify the start-position, the file is read at that absolute character position (0 is the first character in the file, 1 is the second, and so on), otherwise it begins at the current position (the first character when the file is first opened). If you specify num-characters, only that many characters 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-characters equal to 0, the file pointer is reset to character 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 character-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 text file and read its contents into the character
# variable lCharVar 
Do  FileOps.$putfilename(lPathname,'Select a text file','*.txt') Returns lReturnFlag
If  lReturnFlag
  Open file (lPathname,lRefNum)
  Read file as character (lRefNum,lCharVar) Returns lErrCode
  Close file (lRefNum)
End If