DosFileIO

This call performs multiple locking, unlocking, seeking, and I/O operations on an opened file.

Syntax

DosFileIO (FileHandle, CommandList, CommandListLen, ErrorOffset)

Parameters

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:

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:

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.

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:

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.

Return Code

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:

• Unlocking and locking multiple file ranges
• Changing the file position pointer
• 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.

Bindings

C

#define INCL_DOSFILEMGR

USHORT  rc = DosFileIO(FileHandle, CommandList, CommandListLen, ErrorOffset);

HFILE   FileHandle;     /* File handle */
PBYTE   CommandList;    /* Ptr to command buffer */
USHORT  CommandListLen; /* Length of command buffer  */
PLONG   ErrorOffset;    /* Ptr to command error offset */

USHORT  rc;             /* return code */

MASM

EXTRN DosFileIO:FAR
INCL_DOSFILEMGR     EQU 1

PUSH   WORD  FileHandle      ;File handle
PUSH@  OTHER CommandList     ;Command buffer
PUSH   WORD  CommandListLen  ;Length of command buffer
PUSH@  WORD  ErrorOffset     ;Command error offset (returned)
CALL   DosFileIO

Returns WORD