![[Toc]](../../toc.gif)
![[Index]](/idx.gif)
DosFileIO
Bindings: C, MASM
This call performs multiple locking, unlocking, seeking, and I/O
operations on an
opened file.
DosFileIO (FileHandle, CommandList, CommandListLen, ErrorOffset)
FileHandle (HFILE) - input
The handle of the file.
CommandList (PBYTE) - input
Address of the list of entries, indicating the operations to be
performed. CmdLock, CmdUnlock, CmdSeek, and CmdIO operations are
atomic. Thus, the completion of one operation is not dependent upon
the completion of another operation following it in the list.
Operations are performed until all are complete or until one fails.
CmdLock
Lock command structure. To perform lock operations on one or more
regions in a file, a structure is created that has the following
format:
Cmd (USHORT) - input
A value of 0 is required for a lock operation.
LockCnt (USHORT) - input
Number of regions in the file that are to be locked.
TimeOut (LONG) - input
The count in milliseconds until the requesting process is to
resume execution if the requested locks are not available. In
addition to specifying a milliseconds value, the following
values and their meanings may also be specified:
Value Definition
FFFFFFFFH Wait indefinitely until the requested locks become
available.
00000000H Return immediately to the requesting process.
Because the lock operation is atomic, if a lock
within a CmdLock causes a time out, none of the
other locks within the scope of CmdLock are in
force.
Lock
Lock record structure. The CmdLock structure is followed by a
series of records in the following format:
Share (USHORT) - input
Defines the type of access other processes may have to the file
range being locked. Values and their meanings are:
Value Definition
0 Other processes have "No-Access" to the locked range.
The current process has both read and write access to
the locked range. A region with Share = 0 must not
overlap any other locked region.
1 Other processes and the current process have
"Read-Only" access to the locked range. A range locked
with Share = 1 may overlap other ranges locked with
Share = 1, but must not overlap other ranges locked
with Share = 0.
Start (ULONG) - input
Offset into file where region to be locked starts.
Length (ULONG) - input
Length of region to be locked.
CmdUnlock
Unlock command structure. To perform unlock operations on one or
more regions in a file, a structure is created that has the
following format:
Cmd (USHORT) - input
A value of 1 is required for an unlock operation.
UnlockCnt (USHORT) - input
Number of regions in the file that are to be unlocked.
UnLock
Unlock record structure. The CmdUnlock structure is followed by a
series of records in the following format:
Start (ULONG) - input
Offset into file where region to be unlocked starts.
Length (ULONG) - input
Length of region to be unlocked.
CmdSeek
Seek command structure. To perform seek operations on one or more
locked regions in a file, a structure is created that has the
following format:
Cmd (USHORT) - input
A value of 2 is required for a seek operation.
Method (USHORT) - input
Location in file whose offset is used to calculate the new
position of the file pointer by adding to it the offset
specified by Position.
Value Definition
0 Beginning of the file
1 Current location of the file pointer
2 End of the file.
Position (LONG) - input
The distance to move, in bytes.
Actual ULONG - output
New position of the file pointer.
CmdIO
I/O command structure. To perform I/O operations on one or more
locked regions in a file, a structure is created that has the
following format:
Cmd (USHORT) - input
Either of the following values are specified:
Value Definition
3 Read operation
4 Write operation.
Buffer (PBYTE) - input/output
Address of the input or output buffer.
BufferLen (USHORT) - input
Number of bytes requested to be read or written.
Actual (USHORT) - output
Number of bytes actually transferred.
CommandListLen (USHORT) - input
The length in bytes of CommandList.
ErrorOffset (PLONG) - output
Address of the byte offset of the record in which the error occurred.
rc (USHORT) - return
Return code descriptions are:
0 NO_ERROR
5 ERROR_ACCESS_DENIED
6 ERROR_INVALID_HANDLE
33 ERROR_LOCK_VIOLATION
36 ERROR_SHARING_BUFFER_EXCEEDED
87 ERROR_INVALID_PARAMETER
95 ERROR_INTERRUPT
130 ERROR_DIRECT_ACCESS_HANDLE
131 ERROR_NEGATIVE_SEEK
132 ERROR_SEEK_ON_DEVICE
Remarks
DosFileIO combines the following operations into a single request:
o Unlocking and locking multiple file ranges
o Changing the file position pointer
o Performing file I/O.
The ability to combine operations on files provides improved performance
and makes DosFileIO particularly suited to a networking environment.
Unlike DosFileLocks, which unconditionally prevents access to only one
range in a file at a time, DosFileIO permits multiple regions to be
locked. DosFileIO also offers the option of read-only access to locked
regions by the current process and any sharing processes.
If another process attempts to read or write in a "No-access" region, or
if any process attempts to write in a "Read-only" region,
ERROR_ACCESS_DENIED is returned.
A range to be locked must first be cleared of any locked subranges or
overlapping ranges. If a time out occurs before locking can be completed,
DosFileIO returns with an unsuccessful return code. The caller may return
after the time-out period has expired without receiving an
ERROR_SEM_TIMEOUT. Therefore, semaphore time-out values should not be
used for exact timing and sequencing.
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs