@database exec/libraries
@author Gregor Goldbach

@node main "Exec - Libraries - Main"
The libraries are a collection of functions that can be used by every
language - unlike E's modules which are pretty hard to access for a C
programmer. Related functions are put in one library which gets a nice name
so everyone knows at once what it's good for (intuition, graphics, dos,
reqtools etc.).

  @{" Opening and Closing     " link OpenClose}
  @{" Creating                " link Creating}
  @{" Make module or library? " link ModuleOrLibrary}

Gregor Goldbach January 26th 1995
@endnode

@node OpenClose "Exec - Libraries - How to open/close a library"
Open a library via calling

  basepointer := OpenLibrary(name,version)

Example:

  utilitybase := OpenLibrary('utility.library', 37)

name is the library's name (0-terminated), version is a number. Normal
versions are:

  33  -   Kickstart 1.2
  37  -   Kickstart 2.04
  38  -   Kickstart 2.1
  39  -   Kickstart 3.0
  40  -   Kickstart 3.1

Versions 34 to 36 include such exotic Kickstarts as the one for the CDTV.

The result equals NIL if the call failed. If it was successfull you'll get a
pointer to the base of that library. That pointer is to be passed if you call
a function of that library - at least in other languages (e.g. asm), in E you
just have to open the library. However, the pointer stays important, look for
the library base in the according guide.

NOTE: NEVER open exec.library, it the only library that is ALWAYS open!

NOTE: do NOT open dos.library, gfx.library, intuition.library or
      mathtrans.library. E opens them by itself!

NOTE: You HAVE to name the pointers in a special way: to get the base
      pointer's name ShowModule the module EMODULES:<library name>.m. You
      will read a line LIBRARY <base pointer name>. Take that name, E
      requires it.


To close a library just call

  CloseLibrary(basepointer)

Example:

  CloseLibrary(utilitybase)



NOTE: NEVER close exec!

NOTE: NEVER close libraries you didn't open!

Gregor Goldbach January 26th 1995
@endnode

@node Creating "Exec - Libraries -- Creating a library"
Not written yet. Applications welcome!

Gregor Goldbach January 26th 1995
@endnode

@node ModuleOrLibrary "Exec - Libraries -- Shall I make a module or a library?"
I'll try to give you some hints for this.

If you've coded some nice routines that (you think) are awefully useful for
everyone else in the whole Amiga Programming Community, such as a new way of
creating a font-sensitive gui, or a substitution of all standard requesters,
you may think of making a library out of it. However, take care that these
PROCs are coded system-friendly (you always code that way, I forgot :) and
are optimized (small and fast). Additionally, this PROCs should be solutions
for common problems, otherwise they aren't really needed.

If you've coded something that solves a problem of E programmers and gives
them some help, make it a module.

[to be changed]
Gregor Goldbach January 26th 1995
@endnode