Omnis Technical Note TNNO0013

The Notational approach to using FileOps

For Omnis Studio 3.02
By Tom Hume
Raining Data Technical Support


This technical note describes the differences between the two approaches to FileOps in Studio and the required changes needed for the upgrade to Studio 3.02.


FileOps explanation and differences

Omnis Studio provides the means to manipulate files in many ways with the 4GL command set available via the FileOps External Component (Xfileops.dll). More recently, in tandem with this, it is now possible to use the FileOps External Object for enhanced functionality and ease of use. The latter method will be, in effect, replacing the old way of achieving this functionality in Studio 3.02. This technical note is intended to outline the benefits of the External Object approach and ease the transition from the old 4GL commands to the new notation.

There are two distinct sets of FileOps methods; dynamic and static. The dynamic methods are available from the Interface manager when you create an instance of a FileOps object variable. These usually pertain to a particular file i.e. the file that you are working with. To create this object you would need an object variable with a subtype of FileOps. A typical code example could be using the $setfilesize dynamic method:


Do objvar1.$setfilesize([ifilesize])

Where objvar1 is the object variable of subtype FileOps, and ifilesize is a parameter of type Long integer. The static methods are available from the catalogue. External objects can contain static methods that you can call without the need to instantiate the object. These are the methods that would need to be prefixed with 'FileOps'. For example:

Do FileOps.$deletefile(filepath) returns lvError

This deletes the file specified with filepath and returns an error code into lvError if there are any problems and zero if there are not. A full list of error codes is available in the Omnis reference manual.


Conversion

In order to upgrade current applications to Omnis Studio 3.02, the old style 4GL FileOps commands would need to be replaced. An example of converting the old commands to the new notational approach follows. The external command to close a file is:

Close file (refnum) returns lvError

This command closes the file referred to by the file reference number or DOS file handle specified in refnum. Using the $closefile dynamic method of the FileOps external object the required code is:

Do objvar1.$close()

Another example of converting old code to take advantage of the new approach could be highlighted with copy file. The old approach would have been:

Copy file (from-path[,to-path]) returns lvError

Using the new functionality, this is achieved with the following code:

Do FileOps.$copyfile(from-path[,to-path]) returns lvError

The following tables describe the old way of coding FileOps functionality versus the new way.


Static methods:

 Functionality  Old code  New code
Change the working Directory. Change working directory(path) Do FileOps.$changeworkingdir(path)
Copy a file. Copy file(from-path [,to-path]) Do FileOps.$copyfile((from-path [,to path])
Create a directory. Create directory(path) Do FileOps.$createdir(path)
Delete a file. Delete file(path) Do FileOps.$deletefile(path)
Test if a file exists. Does file exist(file\\folder-name) Do FileOps.$doesfileexist(File or Directory)
Obtain a full file or directory listing.

Get files(list-name, first-column, path, file-type [,creator-type];
Get folders(list-name, first-column, path [,8.3])

Do FileOps.$filelist( what [,path,information,filter])
Get specific file information. Get file info(path, type, creator, log-size, phy-size, creat-date, creat-time, mod-date, mod-time) Do FileOps.$getfileinfo(Path, info-flags)
Open file dialogue with specified file type and path. Get file name(path [,dialog-title] [,file-type...] Do FileOps.$getfilename(Path [,prompt, filter, initial directory])
Obtain the current working directory. N/A Do FileOps.$getworkingdir()
Move a file. Move file(from-path, to-path) Do FileOps.$movefile(from-path, to-path)
Save file dialogue with path. Put file name(path [,dialog-title] [,prompt] [,default]) Do FileOps.$putfilename(path [,prompt, filter, initial directory
Rename a file or directory. N/A Do FileOps.$rename( oldname, newname)
Open the select directory dialogue. N/A Do FileOps.$selectdirectory(Path [,prompt, initial directory])
Set file information. Set file read-only attribute(path, read-flag) Do FileOps.$setfileinfo(Path, info-flag, info-setting)
Split a path into composites. Split path name(path, drive-name, directory-name, file-name, file-extension) Do FileOps.$splitpathname(Path, Drive-name, Directory-name, Filename, File-extension)
Read an entire file to a binary variable. Read entire file (path, binary-variable [,'R']) Do FileOps.$readentirefile(filename)
Write an entire file to binary variable. Write entire file (path, binary-variable) Do FileOps.$writeentirefile(filename)


Dynamic methods:

 Functionality  Old code  New code
Close a file Close file(refnum) Do objvar1.$closefile()
Create a file Create file(path [,file-type] [,creator] [,'R']) Do objvar1.$createfile(filename)
Create a temporary file N/A Do objvar1.$createtmpfile()
Get file information Get file info(path, type, creator, log-size, phy-size, creat-date, creat-time, mod-date, mod-time) Do objvar1.$getfileinfo(info-flags)
Get file size N/A Do objvar1.$getfilesize()
Get file position N/A Do objvar1.$getposition()
Check if a file is open N/A Do objvar1.$isopen()
Open a file Open file(path, refnum [,'R']) Do objvar1.$openfile(Filename[,readonly])
Read a file to a character variable Read file as character(refnum, character-variable [,start-position] [,num-characters]) Do objvar1.$readfile(Character variable[, start-position, length])
Read a file to a binary variable Read file as binary(refnum, binary-variable [,start-position] [,num-bytes]) Do objvar1.$readfile(Binary variable[, start-position, length])
Set file info (creater type) Set creator type(path [,file-type] [,creator]) Do objvar1.$setfileinfo(info-flag, info-setting)
Set the file size N/A Do objvar1.$setfilesize([end-position])
Set the position of a file N/A Do objvar1.$setposition(New position)
Write binary variable to a file Write file as binary(refnum, binary-variable [,start-position]) Do objvar1.$writefile(Binary variable[,start-position])
Write character contents to a file Write file as character(refnum, character-variable [,start-position]) Do objvar1.$writefile(Character variable[,start-position])
Set file attribute Set file read-only attribute(path, read-flag) Do objvar1.$setfileinfo(info-flag, info-setting)
Truncate a file N/A Do objvar1.$setfilesize([end-position])
Open a resource fork (Mac only) Open resource fork(path, refnum [,'R']) Do objvar1.$openresources(filename[,read-only])


a.) The static methods - The catalogue>>Functions>>FileOps
b.) The dynamic methods - available from the Interface Manager when the object var is instantiated

Although not recommended, it is possible that backward compatibility could be retained in terms of FileOps. In other words, applications developed prior to Studio 3.02 could still be upgraded to take advantage of all the other benefits available in 3.02 and still use the old style FileOps approach with external commands. This could be achieved by copying the old external Xfileops.dll from the Studio 3.0 tree and placing it in the External folder of the Studio 3.02 tree. However, there are important considerations that one should bear in mind. The old FileOps commands are not supported on Mac OS X so there could be inconsistencies when deploying cross-platform. The commands will essentially be obsolete and the added functionality of the new way would not be available so code would also be inconsistent with regards to FileOps.