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:
Obviously, it reads instead of writes. Otherwise it would be silly to call it "read!"
Note that the "buf" argument is no longer marked as "const". That means that the API definitely can change the contents of the variable that buf points to!
In fact, that's where read will store the information that it loads from the stream file.
The "nbyte" parameter tells read the size of the variable that the "buf" parameter is pointing to. It's true that read() will try to read that many bytes from the disk, but if you're at the end of the stream file, read() may read fewer bytes than you've specified in the "nbyte" argument. Don't treat that as an error!
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