DosFileIO

Description

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:

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.

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.

Example Code

C Binding

#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 Binding

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