Blitz:OS Calls

OS calls use the Amiga API directly, ensuring compatibility with the operating system and the ability to use the techniques recommended by official SDK guidelines. The Amiga APIs are designed to be simple enough to use with the C language and so some almost all examples you will find are written in C. Nevertheless, with the more advanced features of Blitz mirroring the equivalent C features (structs, pointers etc.), it is possible to do pretty much anything with the API that you can do with C.

The AmiBlitz include files are generally written using the OS calls, so using these includes will allow you to easily access the OS functions properly without having to get deep into the official SDK documentation and trying to figure out how to adapt the examples to Blitz code. However there are also times when accessing the API directly is the simplest or only option.

Using OS Libraries

Blitz includes direct calls for several of the key Amiga libraries already built in as keywords. To call a specific function in Blitz, the name of the call is entered with an underscore on the end. This underscore denotes a command directly called from a library, which prevents any clashes with Blitz keywords. The official SDK is the best place to reference the specifics of each library and call, but in general, in contrast to most built in commands, library calls can be treated as either a statement or a function by simply using the relevant syntax. For example:

Execute_ "SYS:Prefs/Font", 0, 0

This tries to run the program given in the quote marks.

success = Execute_ ("SYS:Prefs/Font", 0, 0)

This is the same call used as a function instead, which allows the result to be saved. For many calls, the result is a way of determining if the call was completed successfully or not. It also usually contains important information if successful which would be required later, such as file handles or the address of a created object. Brackets must also be placed around the parameters to treat a call as a function.

If a function is treated as a statement, the return value is discarded. If a statement is treated as a function, the return value is 0.

There is no requirement to open or close libraries used in this manner - this is handled automatically by Blitz on program startup and end.

OS Structs and Constants

Many OS functions use structs and constants that are defined in the standard OS C header files. Blitz can't use the C header files directly (since they're in C code!), so it provides an alternative in the form of resident files. These files are pre-compiled code that will then be included in your program. Generally they're similar to using include files but since they're already compiled they don't need to be recompiled every time you compile your program, saving compilation time.

C header files can also be translated into Blitz syntax and used for your program with an Include command, but this adds to the compilation time and isn't required for the standard OS libraries.

All the standard OS structs and functions are contained in a file called amigalibs.res, which you add to the list in the Compiler Settings window. AmiBlitz knows where to find this file automatically so only the name is required, however older Blitz Basic 2 installations may need the full path, which would be BlitzLibs:amigalibs.res. Once this file is added to the settings, any OS calls and code should be able to find all the definitions they need.