FILEOPS

External objects

The FileOps dynamic functions allow you to manipulate files. To use these methods, you must declare an object variable, and set its subtype to the FileOps external object. You then call the method using the syntax object.$methodname(). You can use the Interface Manager to view the methods of the object.

Methods

Method Description
$closefile $closefile() closes the file. If you open a file using $openfile(), $openresources(), $create() or $createtmpfile(), then you should close it by calling this function, when you have finished using it. This function does not return a value.
$createfile $createfile(cFilePath[,cType,cCreator,bRes]) creates and opens an empty file with pathname cFilePath. For macOS, cType and cCreator are the file and creator types for the new file; boolean bRes indicates if the file is to have a resource fork
If the file already exists, $createfile() replaces it with an empty file. All directories in the pathname specified in the cFilePath parameter must already be present. The optional parameters are only available on macOS.
$createtmpfile $createtmpfile() creates and then opens a temporary file, ready for you to write data to it.
$createtmpfile() returns a boolean value, which is true if the temporary file was successfully created and then opened.
$getfileinfo $getfileinfo(iInfoFlags) Returns a list containing file information for the open file associated with the object. iInfoFlags is a combination of kFileOpsInfo... constants. If an error occurs, the function returns an empty list.
$getfilesize $getfilesize() returns the size in bytes of the open file associated with the object. If an error occurs, the function returns -1.
$getposition $getposition() returns the current position of the open file associated with the object.
The current position is the byte index to the position in the file where the next function which reads or writes data, will read or write. The first byte in the file has position zero. If an error occurs, the function returns -1.
$isopen $isopen() returns true if there is an open file associated with the object, false otherwise.
$openfile $openfile(cFilePath[,bReadonly=kFalse]) opens an existing file. cFilePath is the pathname of the file to be opened.
The bReadonly parameter is optional. It is a boolean which defaults to false. If you pass true, then $openfile() will open the file in read-only mode.
$openfile() returns a boolean value, which is true if the file was successfully opened.
$openresources $openresources(cFilePath[,bReadonly=kFalse]) Opens the resource fork of the specified file. This function applies to macOS only.
cFilePath is the pathname of the file for which the resource fork is to be opened.
The bReadonly parameter is optional. It is a boolean which defaults to false. If you pass true, then $openresources() will open the resource fork in read-only mode.
$openresources() returns a boolean value, which is true if the resource fork was successfully opened.
$readcharacter $readcharacter(iEnc,&cData[,&iOffset=0,iMaxLen=0]) Reads characters encoded using iEnc (a kUniType... constant (not kUniTypeBinary/Character)) into cData. Reads entire file, or iMaxLen chars from byte offset iOffset and returns next iOffset
$readfile $readfile(&xVariable[,iStartPos,iLength]) reads data from the open file associated with the object. Binary xVariable receives the data read from the file.
You are recommended to use $readcharacter() to read character data, otherwise you may get unexpected results.
If you omit iStartPos and iLength, $readfile() reads all the remaining data from the current position to the end of the file; you can set the current position using the function $setposition(). Otherwise, you can specify the position from where the data is to be read, using the iStartPos parameter, and you can specify the number of bytes to read using the iLength parameter.iLength must not exceed the data available from iStartPos to the end of the file.
$readfile() returns a boolean value, which is true if the data was successfully read. After reading the data, the current position addresses the byte after the last byte read, or end of file, if no further data remains.
$setfileinfo $setfileinfo(iInfoFlag,vInfoValue,...) sets a file information item for the open file associated with the object to vInfoValue. iInfoFlag is a kFileOpsInfo... constant.
The function returns an error code, or zero if successful: See the FileOps function error codes.
$setfilesize $setfilesize(iNewSize) sets the file size to iNewSize bytes, for the open file associated with the object. Any data after the first iNewSize bytes is lost.
$setfilesize() returns a boolean, which is true if the new size was successfully set.
$setposition $setposition(iNewPos) sets the current position, for the open file associated with the object.
The current position is the byte index to the position in the file where the next function which reads or writes data, will read or write. The first byte in the file has position zero. $setposition()returns a boolean, which is true if the new position was successfully set.
$writecharacter $writecharacter(iEnc, cData [,bAppend=kFalse]) Writes cData to the file, encoded using the encoding iEnc (a kUniType... constant (not kUniTypeAuto/Binary/Character)).If bAppend iskFalse, the entire file contents are replaced
$writefile $writefile(xVariable[,iStartPos]) writes data to the open file associated with the object. Binary xVariable contains the data to write to the file.
You are recommended to use $writecharacter() to write character data, otherwise you may get unexpected results.
By default, $writefile() writes the data starting at the current position. You can specify an alternative position using the iStartPos parameter.
$writefile() returns a boolean value, which is true if the data was successfully written. After writing the data, the current position addresses the byte after the last byte written, or end of file.