1.6. Looking at our example from OS/400
In our hello world example, we defined a bunch of prototypes in our D-specs that told the system what APIs we wanted to call, and how the parameters were to be passed to them. If you don't understand how prototypes work, this might be a good time to whip out a book on prototypes and brush up.
When we get to the C-specs, you'll see that we are calling the open() API, like this:
c eval fd = open('/helloworld': 
c O_CREAT+O_TRUNC+O_WRONLY:
c (6*64)+(6*8)+(4))
c if fd < 0 
c eval Msg = 'open failed!'
c dsply msg
c eval *inlr = *on
c return
c endif
- Here we tell the API that the file we want to open is in the root directory ("/") and is called "helloworld", and that the result of the call should be stored in the variable called "fd" (which is shorthand for "file descriptor")
- These flags tell the API that we want to create the file if it doesn't already exist (O_CREAT), truncate the file to zero bytes if it does exist (O_TRUNC) and that we're opening the only for writing to it (O_WRONLY) and not for reading.
-
"Truncating" the file can be thought of as "clearing" the file. All it does is delete any data that currently exists in the file.
- This confusing looking equation is the file's "mode", also called the "permissions" that we're giving to it. This tells the operating system who is allowed to read this file, who is allowed to write to it, and who is allowed to execute/search it (if it is a program or directory, respectively)
-
Because this "mode" is confusing, and hard-to-read, I use named constants to make it clearer. If you look at the previous example, you'll see that I used named constants to make it easier to read. I'll use some more standardized (though, arguably harder to read) constants in a later chapter.
-
We'll talk more about file modes in the upcoming chapter. For now, just know that we're giving read & write permission to ourselves, read & write permissions to anyone in our "group", and read-only permissions to everyone else.
- If an error occurred, the system will return a -1 to our "fd" variable. Therefore, we check for an error, and if one occurred, we'll report it to the user, and end the program.
We then proceed to write the string 'Hello World!' to the file, close it, and end the program.
To see if it worked, return to your trusty OS/400 command line and type:WRKLNK '/*'
OS/400 will bring up the "Work with Object Links" screen which shows you a list of all of the objects in the root directory of the IFS. (Depending on what's stored here on your system, there could be many pages of information.) Find the file called 'helloworld' in the list of object links. You'll note that it has a 'Type' of 'STMF', which means that it is a stream file.
Place a 5 next to it, and OS/400 will show you the contents of the stream file. You should now see that it contains the words "Hello World!" just as we expected. Press the F3 key to get back to the "Work With Object Links" screen.
Unless you have some nifty use for the helloworld file you created, let's delete it now, by putting a 4 next to it to delete it.
Yes, it's really that simple! Aside from the prototypes and maybe the file mode, this program is really short and easy to follow. Using this same technique, you can write almost anything to a stream file! We'll cover this more in depth, and show you how to read a stream file in the next chapter.