2.4. Reading a stream file with the read() API

The read() API is the exact opposite of the write() API. It reads bytes of data from a stream file, and stores them into the area of memory that you point it to.

Here's the C language prototype of read():

     int read(int fildes, void *buf, size_t nbyte);
   

This prototype is so much like the write() API that I won't even describe the process of converting it from C to RPG. From reading about write(), you should already understand. So, without any more long-winded ramblings, here's the RPG prototype:

     D read            PR            10I 0 extproc('read')          
     D   fildes                      10I 0 value                    
     D   buf                           *   value                    
     D   nbyte                       10U 0 value                    
   

Make sure you put that in your copy of the IFSIO_H member.

In many ways, read() is very similar to write(). Like it's counterpart, it can be used to work with any byte values. It does not care if the data is numeric or character or part of a graphic or sound format. And, like write() it takes 3 parameters, and returns an integer. There are, however, some crucial differences:

You call the read() API like this:

     c                   eval      len = read(fd: ptr2buf: %size(buf))
     c                   if        len < 1
     c                   goto      no_more_to_read
     c                   endif