Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSFILEMGR
 
USHORT DosFileIO(hf, pbCmd, cbCmd, pusErr);
HFILE hf;          /* file handle                    */
PBYTE pbCmd;       /* pointer to buffer for commands */
USHORT cbCmd;      /* length of command buffer       */
PUSHORT pusErr;    /* pointer to error offset        */
 
The DosFileIO function performs multiple lock, unlock, seek, read, and write
operations on a file.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hf         Identifies the file on which to perform the commands. This handle
           must have been created previously by using the DosOpen function.
 
pbCmd      Points to the buffer that contains one or more of the following
           structures: FIOLOCKCMD, FIOLOCKREC, FIOUNLOCKCMD, FIOUNLOCKREC,
           FIOSEEKCMD, or FIOREADWRITE.
 
cbCmd      Specifies the length (in bytes) of the pbCmd parameter.
 
pusErr     Points to a variable that receives the byte offset of the
           structure that caused an error. The offset is relative to the
           beginning of the buffer pointed to by the pbCmd parameter.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_ACCESS_DENIED
     ERROR_DIRECT_ACCESS_HANDLE
     ERROR_INTERRUPT
     ERROR_INVALID_HANDLE
     ERROR_INVALID_PARAMETER
     ERROR_LOCK_VIOLATION
     ERROR_NEGATIVE_SEEK
     ERROR_SEEK_ON_DEVICE
     ERROR_SHARING_BUFFER_EXCEEDED
 
Comments
 
The DosFileIO function allows you to combine the following operations into a
single function call:
 
♦  Locking and unlocking multiple file ranges
 
♦  Changing the file-position pointer
 
♦  Reading and/or writing
 
Combining these operations into one call can improve system performance,
particularly in a networking environment.
 
The DosFileIO function provides a simple mechanism for denying other
processes read/write or write access to regions of the file. If another
process attempts to read from or write to a no-access region, or attempts to
write in a read-only region, an error is returned. If a time-out occurs
before the locking operation is complete, DosFileIO returns an error to the
calling process.
 
Since the calling process may return after the time-out period has expired
without receiving an ERROR_SEM_TIMEOUT message, semaphore time-out values
should not be used for exact timing or for determining the sequence of I/O
operations.
 
Before a range is locked, it must be cleared of any locked subranges or
locked overlapping ranges.
 
Each I/O operation completes before the next one begins. The operations
continue until all are complete or until one fails.
 
Example
 
This example opens the file abc.txt, allocates memory for the command
buffer, initializes the commands in that buffer, and calls DosFileIO to move
the file 10 bytes into the file and then read from the file:
 
HFILE hf;
USHORT usAction;
SEL sel;
BYTE abBuf[512];
LONG lError;
 
PFIOREADWRITE pfiorw;
PFIOSEEKCMD pfioseek;
 
DosOpen("abc.txt", &hf, &usAction, 0L, FILE_NORMAL, FILE_OPEN,
    OPEN_ACCESS_READONLY | OPEN_SHARE_DENYNONE, 0L);
DosAllocSeg(sizeof(FIOSEEKCMD) + sizeof(FIOREADWRITE), &sel, SEG_NONSHARED);
 
pfioseek = MAKEP(sel, 0);
pfioseek->usCmd = FIO_SEEK;
pfioseek->fsMethod = FILE_BEGIN;
pfioseek->cbDistance = 10L;
 
pfiorw = MAKEP(sel, sizeof(FIOSEEKCMD));
pfiorw->usCmd = FIO_READ;
pfiorw->pbBuffer = (PVOID) abBuf;
pfiorw->cbBufferLen = sizeof(abBuf);
 
DosFileIO(hf,                                    /* file handle    */
    MAKEP(sel, 0),                               /* buffer address */
    (sizeof(FIOSEEKCMD) + sizeof(FIOREADWRITE)), /* buffer size    */
    &lError);                         /* address of error variable */
 
See Also
 
DosChgFilePtr, DosFileLocks, DosOpen, DosRead, DosWrite, FIOLOCKCMD,
FIOLOCKREC, FIOREADWRITE, FIOSEEKCMD, FIOUNLOCKCMD, FIOUNLOCKREC
 
                                      ♦