Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File11.5.18.3  How do I use a library?                                 TOS

To start with, one needs the object module SLB_BIND for calling the 
two new DOS functions, for which one has to link the file SLB.H.

For each library used one declares a descriptor of the type SHARED_LIB 
and a function pointer of the type SLB_EXEC.

Each library is opened with Slbopen (opening and closing should only 
take place in user-mode), during which the following parameters are 
passed:

 char *name   The name of the library, in capitals, including the 
              extension (".SLB"). The library name is also the 
              filename.
 char *path   If this parameter is not NULL, then first of all a 
              search will be made for the library (the path must end 
              with '\' in MagiC 5.20; this is no longer necessary in 
              MagiC 6). The path should be an absolute one, so that 
              the shared library knows where it lies. If the parameter 
              is NULL or the library was not found in the specified 
              path, then a search is made in the XTENSION folder.
              From MagiC 6 onwards the environmental variable SLBPATH 
              will be evaluated. Like PATH it contains a list of 
              search-paths, each separated by ';'. If the variable is 
              defined no additional search will be made in the 
              XTENSION folder.
 LONG min_ver Minimum required version number of the library.
              If a program needs, say, version 3 but the library 
              present is only version 2, then ERANGE will be returned. 
              The return value will be the actual version number of 
              the library.
 SHARED_LIB *sl Pointer to the descriptor. When the library is opened 
              the descriptor will be entered here.
 SLB_EXEC *fn Pointer to the function pointer. When the library is 
              opened the function pointer will be entered here.

Return values can be:

  >= 0        All OK, version number of the library
  ERANGE      Version number too low
  EACCDN      Library already opened by this process
  EFILNF      Library not found
  ENSMEM      Insufficient memory free
  ...         Other error-codes.

The library can now be used and finally closed again with Slbclose. 
This is not absolutely necessary as all open libraries are closed 
automatically at program termination, but it is good programming 
practice. On no account may a library be closed more than once, since 
the kernel can not recognize such errors.

Some libraries such as EDITOBJC.SLB, for instance, install new system 
calls, in this case the AES calls 210..217. For these libraries the 
function pointer is not needed. Otherwise all functions of the library 
are called via the function pointer. The library call function is 
declared in the following way:

 typedef LONG (cdecl *SLB_EXEC)( SHARED_LIB *sl, LONG fn,
        WORD nargs, ... );

As regretably Pure-C has an error here, I was forced to declare this 
functions as 'typedef LONG (*SLB_EXEC)( void , ... );'. Unfortunately 
this inhibits all type checking. So take care!

The call expects the following parameters:

     The descriptor of the library
     A longword (!) for the function number
     A WORD, that specifies the number of arguments in WORDs
             (i.e. all "..." arguments)
     Further arguments, depending on the function.

The best way is to make the call via a macro, which should be defined 
in a header file for the library, e.g.:

JPEG.H:

#define SLBJPEG_WANDELN (a,b) (*slbjpeg_exec)(slbjpeg, 7L, 4, a, b)

With this slbjpeg_exec and slbjpeg will be ascertained at Slbopen, 7L 
is the function number for the call WANDELN (convert), 4 describes the 
length of the following arguments (<a> and <b> are two pointers => 2*4 
bytes => 4 WORDs), and a and b are the arguments of the function 
WANDELN.

If the function is not present (the library contains a NULL-pointer 
for this function, or the function number is higher than the number of 
functions actually present), one will receive EINVFN as the function 
result (in fact this only works correctly from MagiC 6 onwards).