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]; |
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.