Using syslib

  1. How to use syslib
  2. Consistent naming scheme
  3. Startup files and the like
  4. Using syslib from assembler

How to use syslib

Using syslib is not difficult. All that has to be done is include the proper header files when compiling, and making sure that the file has a suitable format for dynamic linking. In short this normally means that the syslib library file has to be linked in (by passing the -lsms option to the linker).

When you are mixing syslib with the c68 library routines (and thus using the c68 startup file), then you should reference the _InitSysLib function (no parameters) somewhere in your code (this routine does nothing except making sure that the linker creates a proper linkage area for the DLL Manager.

Consistent naming scheme

In syslib (and also PROforma and ProWesS), we have attempted to make the naming scheme and parameter passing conventions as consistent as we could.

The general rule for return values is that the return value for a function is an Error code. When actual results are requested, they are filled into a parameter (pointer given). There is only one type of exception to this rule, and that is when a function (or macro) is used to investigate a state, and can only return TRUE or FALSE.

Generally speaking, parameters are always passed in the following order.

Startup files and the like

When using syslib, we recommend (unless you also want to use the c68 library functions), to use some specialised startup files. These automatically call the DLL Manager to link the DLL's and do the program relocation. For executables, this also allows the executable to be loaded as a resident extension, in which case the program will be linked as an executable thing (with the program name as thing name).

The process of building the output files consists of two passes. These passes slightly depend on the type of file which is produced.

executable
resident extension
external module

Using syslib from assembler

There are no real problems when you try to call syslib from assembler. You just have to mimic the naming and parameters passing conventions from c68 when calling syslib functions.

There is only one thing which has to be considered. In this case, it is best to use ld the c68 linker, and the standard startup files which are also used when compiling c programs.

The c68 naming scheme always adds an underscore before the names of globally visible function names and data structures. This should be remembered when calling syslib functions. Also, you have to be very careful with the parameters passing and stack cleanup. This is normally handled and checked by the compiler, but assembler is not that smart.

Following the c68 register saving conventions, all the syslib functions can smash d0/d1/a0/a1. All other registers retain their values. If a function returns a value, the result is passed in d0. For a double (which does not fit in d0), d1 is also used to return (the sond long word of) the result.

Although c68 allows an int to be either two or four bytes in length, large parts of syslib actually rely on it being four bytes. All paameters are always passed in as little space as possible, that is

However, in variable argument lists (...), the char and short arguments are also passed in a long word.
PROGS, Professional & Graphical Software
last edited February 20, 1995