FileIO
If you're reading this, you almost certainly have data stored in a Synergy data file of some kind. And if you expose this data as a data object, you'll need a way to read, write, update, and delete records in your files.
This is where Harmony.Core.FileIO.DataObjectIOBase<T> comes in. With this class, we've implemented all the glue that's needed between a Synergy record in memory and a usable data object.
Using DataObjectIOBase as a starting point, we made Harmony.Core.FileIO.IsamDataObjectIO<T> with a default implementation that should work for most Synergy data. However, if you already have routines that perform file I/O operations along with validation or other business logic, you can implement your own I/O class.
We have included a basic example here to show you how to replace our default file I/O routines with those you already use in your application.
IsamDataObjectIO is not inherently thread safe. Internally it uses a single file channel to perform its file I/O operations, so multiple concurrent operations performed on a single IsamDataObjectIO will result in exceptions at runtime. And multiple interleaved but non-concurrent requests can ruin the file channel's position and locking status.
So in general, we recommend that you create an IsamDataObjectIO object when you need it, use it for a short time for a single logical unit of work, and then dispose of it when you're finished. Because the class internally uses IFileChannelManager, creating and destroying IsamDataObjectIO objects is very cheap.
IsamDataObjectIO includes default processing for file I/O errors like Key Not Same. But if you need to run custom code when a particular error occurs, you can inherit from IsamDataObjectIO and overload one of the following handling methods:
-
OnEOF - Invoked when the end of the file is reached.
-
OnRecordLocked - Invoked when the record your program is trying to lock is already locked.
-
OnKeyNotFound - Invoked if your program is trying to look up a record by key but the record doesn't exist or the program has read past it.
-
OnDuplicateKey - Invoked if your program attempts to add a record to a file, but the file already contains a record with the same value for a key that is not marked as allowing duplicates.
-
OnNoCurrentRecord - Invoked if your program attempts to write a record without locking it first.
-
OnRecordNotSame - Invoked if your program attempts to update a record using its GRFA when the record has been changed since the program last read it.
-
OnInvalidOperation - Invoked if your program issued an I/O statement that was not allowed by the mode in which the file was opened.
-
OnInvalidRFA - Invoked if your program specified an invalid RFA on an I/O operation.
-
OnDeletedRecord - Invoked if your program has a record attempting to access with an RFA has been deleted or moved.
-
OnIllegalKey - Invoked if your program's specified key name does not match a key, or the specified key index is not in the range defined for the ISAM file. This can also be invoked if your program has an implied key specification does not match a key.
-
OnFileIOException - Invoked for general Synergy file I/O exceptions that are not otherwise covered by the other handlers.
-
OnException - Invoked for exceptions that aren't related to file I/O.
Timeouts can be set for your read and write operations. DataObjectIOBase has a writable property called TimeoutSeconds, which specifies the maximum about of seconds to wait for lock operations to complete. This property defaults to five seconds, and can be set to as low as one second. Operations that exceed this timeout will error out with RecordIslocked.
With a default install of xfServer on OpenVMS there is a limit of 256 channels open per connection. If you're connecting to an OpenVMS xfServer instance you may run out of channels inside the EF Core Provider. Inside the Harmony Core file channel manager we have a soft limit before file channels will be scavenged but this limit is higher than 256. The best way to solve file open issues in this case is to edit synergy_startup.com on the vms machine to increase the /file_limit from 256 to 1024.
The channel soft limit can be controlled by setting Harmony.Core.FileIO.FileChannelManager.SoftChannelLimit to a number between 1 and 1024 during startup before the FileChannelManager is initialized.