DosFileIO

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:
• 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.

  ---

  [Back: DosExitList]
  [Next: DosFileLocks]