DosListIOL

DosListIOL performs the specified number of seek/read or seek/write operations or both.

Syntax

DosListIOL (CmdMode, NumEntries, pListIO)

Parameters

CmdMode (LONG) input

This specifies the mode in which the operations should be performed.

Valid modes are:

LISTIO_ORDERED: Operations are performed synchronously in the given order.

LISTIO_UNORDERED: Operations are performed independent of order.

NumEntries (LONG) input

The number of seek/read or seek/write operations in the list.

pListIOL (PLISTIOL) input/output

Pointer to an array of NumEntries LISTIO data structures which contain the information necessary to perform the seek/read and seek/write operations.

Return Code

ulrc (APIRET) returns

DosListIOL returns one of the following values:

• 0 NO_ERROR
• 5 ERROR_ACCESS_DENIED
• 6 ERROR_INVALID_HANDLE
• 19 ERROR_WRITE_PROTECT
• 26 ERROR_NOT_DOS_DISK
• 29 ERROR_WRITE_FAULT
• 33 ERROR_LOCK_VIOLATION
• 87 ERROR_INVALID_PARAMETER
• 109 ERROR_BROKEN_PIPE
• 234 ERROR_MORE_DATA

Remarks

DosListIOL applies the same restrictions for each seek/read and seek/write control block as would be applied if the requests were issued separately with DosSetFilePtrL, DosRead, and DosWrite.

Each request control block contains fields for the Actual number of bytes read/written and the operation return code. These fields are updated upon completion of each request; therefore, care must be taken that the memory containing the control block array not be deallocated or manipulated by another thread before the DosListIOL request returns.

There are two valid modes for the list of I/O operations to be processed:

• Ordered - This mode guarantees the order in which the operations will be performed. The API will return with an error code corresponding to the first failed request and will leave the following requests unissued. This provides a synchronous sequence of automatic seek/read and seek/write requests. This is the only mode that is compatible with file systems other than the raw file system.
• Unordered - This mode does not guarantee the order of issue or completion of the requests. The API will return with an error code if any request fails. Additionally, each request in the list will be issued, even those following a failed operation. This mode is valid for the raw file system only.

This function was included as an addendum of the OS/2 Toolkit 4.5

Example Code

In this example, the source file SOURCE.DAT is copied to TARGET.DAT. First, the information about the source file is obtained by calling DosQueryPathInfo. Next, the target file is created with the same size as the source file. Using a series of calls to DosListIO, the content of the source file is copied to the target file.

#define INCL_DOSFILEMGR          /* File Manager values */
#define INCL_DOSERRORS           /* DOS Error values    */
#define INCL_LONGLONG
#include <os2.h>
#include <stdio.h>
#include <memory.h>
#define SOURCE_PATHNAME "source.dat"
#define TARGET_PATHNAME "target.dat"
#define BUFFER_SIZE 4096

int main(void) {
   FILESTATUS3L  fsSource = { {0} };          /* Buffer for information about source file  */
   LONGLONG llSize;                           /* Source file size (totalcopy size) */
   HFILE  hfSource   = 0L;                    /* Handle for source file */
   HFILE  hfTarget   = 0L;                    /* Handle for target file */
   ULONG  ulAction = 0;                       /* Action taken by DosOpen*/
   LISTIOL listIOCtrlBlks[2];                 /* List IO control blocks */
   ULONG  ulNumCtrlBlks;                      /* Number of control blocks*/
   BYTE   pData[BUFFER_SIZE];                 /* Buffer to hold copy data */
   ULONG  cbData;                             /* Size of data for each IO operation */
   APIRET rc = NO_ERROR;                      /* Return code */

   /* Query information about the source file to obtain its size */
   rc = DosQueryPathInfo(SOURCE_PATHNAME, FIL_STANDARDL,  fsSource, sizeof(fsSource));
   if (rc != NO_ERROR)
   {
      printf("DosQueryPathInfo failed, return code = %u\n", rc);
      return 1;
   }

   llSize = fsSource.cbFile;

   /* Open the source file for reading */
   rc = DosOpenL(SOURCE_PATHNAME,               /* File path name */
                &hfSource,                      /* File handle */
                &ulAction,                      /* Action taken */
                0,                              /* File primary allocation */
                FILE_ARCHIVED | FILE_NORMAL,    /* File attribute */
                OPEN_ACTION_FAIL_IF_NEW |       /* Open existing file */
                OPEN_ACTION_OPEN_IF_EXISTS,
                OPEN_FLAGS_NOINHERIT |
                OPEN_SHARE_DENYNONE  |
                OPEN_ACCESS_READWRITE,          /* Open mode of the file */
                0L);                            /* No extended attribute */

   if (rc != NO_ERROR)
   {
      printf("DosOpenL failed to open %s, rc = %u\n", SOURCE_PATHNAME, rc);
      return 1;
   }

   /* Open the target file for writing */
   rc = DosOpenL(TARGET_PATHNAME,               /* File path name */
                &hfTarget,                      /* File handle */
                &ulAction,                      /* Action taken */
                llSize,                         /* Target equals source file size */
                FILE_ARCHIVED | FILE_NORMAL,    /* File attribute */
                OPEN_ACTION_CREATE_IF_NEW |     /* Open new file */
                OPEN_ACTION_FAIL_IF_EXISTS,
                OPEN_FLAGS_NOINHERIT |
                OPEN_SHARE_DENYNONE  |
                OPEN_ACCESS_READWRITE,          /* Open mode of the file */
                0L);                            /* No extended attribute */

   if (rc != NO_ERROR)
   {
      printf("DosOpenL failed to create %s, rc = %u\n", TARGET_PATHNAME, rc);
      DosClose(hfSource);  /* Remember to close source file before exiting */
      return 1;
   }

/* Initialize listIOL control blocks */
   memset(listIOCtrlBlks, 0, sizeof(listIOCtrlBlks));

   listIOCtrlBlks[0].hFile = hfSource;                      /* Source file handle */
   listIOCtrlBlks[0].CmdFlag = LISTIO_READ | FILE_CURRENT;  /* Read operation */
   listIOCtrlBlks[0].Offset = 0;
   listIOCtrlBlks[0].pBuffer = (PVOID)pData;

   listIOCtrlBlks[1].hFile = hfTarget;                      /* Target file handle */
   listIOCtrlBlks[1].CmdFlag = LISTIO_WRITE | FILE_CURRENT; /* Write operation */
   listIOCtrlBlks[1].Offset = 0;
   listIOCtrlBlks[1].pBuffer = (PVOID)pData;

   while (llSize) {
      if (llSize < BUFFER_SIZE) {
         cbData = llSize;
      } else {
         cbData = BUFFER_SIZE;
      }
      llSize = llSize - cbData;   /* adjust remaining copy size */

      listIOCtrlBlks[0].NumBytes = cbData;
      listIOCtrlBlks[1].NumBytes = cbData;

      ulNumCtrlBlks = 2;
      rc = DosListIOL(LISTIO_ORDERED,
                     ulNumCtrlBlks,
                     listIOCtrlBlks);
      if (rc != NO_ERROR)
      {
         printf("DosListIOL error  rc = %u\n", rc);
         break;
      }
      else
      {
         /* Check return code from the read operation */
         if (listIOCtrlBlks[0].RetCode != NO_ERROR)
         {
            printf("DosListIOL read operation failed, rc = %u\n", listIOCtrlBlks[0].RetCode);
            break;
         }

         /* Check return code from the write operation */
         if (listIOCtrlBlks[0].RetCode != NO_ERROR)
         {
            printf("DosListIOL write operation failed, rc = %u\n", listIOCtrlBlks[0].RetCode);
            break;
         }
      }
   } /* end while */

   DosClose(hfSource);                /* Close source file */
   DosClose(hfTarget);                /* Close target file */

   return NO_ERROR;
}

Related Functions

• DosOpenL
• DosSetFilePtrL
• DosRead
• DosWrite