home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / dirs / libtool_393.lzh / LibTool / AsmComplex / Complex.DOC < prev    next >
Text File  |  1990-10-28  |  4KB  |  81 lines
  1.   This describes how to make the "complex.library" assembly example. If you
  2. have not made the "simple.library" assembly example, do so first.
  3.   The primary difference between the complex and simple example is that the
  4. complex example introduces the Init, Expunge, Open, and Close vectors, and a
  5. scheme for avoiding global data.
  6.   When a library is first loaded, an initialization routine is called. This is
  7. the routine that opens the intuition, graphics, DOS, and exec libraries on
  8. behalf of your lib functions. There are some other things that you might want
  9. to do (once only) when the lib is first loaded. For example, you might want
  10. to set up a port, or start a separate task. These are things that you only
  11. wish to do once at the beginning. If you need to do something like this, you
  12. should write a function, and place it with your lib functions. Now, add a
  13. ##init line to your fd file followed by the name of your function. For example,
  14. if your function is myInit().
  15.  
  16. ##init myInit
  17.  
  18.   You'll probably want to free that port, or remove that task when you're lib
  19. finally gets removed from memory. You do this by writing a function to free/
  20. close anything that you allocate/open in your Init function. Assume that we
  21. wrote a function called myFree(). Add this line to the fd file
  22.  
  23. ##expu myFree
  24.  
  25.   On the other hand, there are things that you might need to do once for each
  26. task that uses the lib. For example, you may want to allocate some memory for
  27. each task to be used as a "work buffer". Each task needs its own memblock to
  28. be allocated once when the task opens the lib. Write a function to do this, and
  29. set it up as the Open vector. Here is an example of an Open vector, OpenIt().
  30.  
  31. ##open OpenIt
  32.  
  33.   Now, you'll want to free each task's memory when the task closes the lib. You
  34. do this by writing a function and setting it up as the Close vector. For
  35. example, you might add this line to the fd file for some CloseIt() function.
  36.  
  37. ##clos CloseIt
  38.  
  39.   You can set up one or all four of the above vectors. Just remember that the
  40. Init function only gets executed once when the lib is loaded. The Open routine
  41. gets executed everytime that an application opens the library. You should free/
  42. close anything that you allocate/open in the Init function, with a corresponding
  43. Expunge function. Likewise, a Close function complements an Open function.
  44.   The Close and Expunge vectors return nothing. The Init and Open vectors should
  45. return d0 = 1 if everything went well, or d0=0 for an error. If an error,
  46. this will force the application's OpenLibrary to fail. Your Init and Open
  47. routines are responsible for cleaning up their partially allocated resources.
  48.   The complex.library sets up an Open and complimentary Close vectors for the
  49. above purpose. Each task gets a work buffer which we use for making a newWindow
  50. structure. This work buffer gets linked into a master list so that we can keep
  51. track of all of them. We use the address of each task to tag its work buffer.
  52.   Note these 2 functions, OpenUp() and CloseUp() in the file "Complex.asm".
  53. Also, note how I set them up in the fd file "Complex.fd".
  54.   This library also has 3 functions:
  55.  
  56. MakeWindow - opens a window
  57. PrintMsg   - prints a msg and waits for a CLOSEWINDOW
  58. RemWindow  - closes the window
  59.  
  60.   Note that we have changed the name and id of the library. Also note how I
  61. use the ##ret to declare the return values of the lib functions.
  62.  
  63.   To make the library, assemble "Complex.asm" as "Complex.o". Invoke LibTool
  64. on "Complex.fd" to make our asm INCLUDE file and libstart code.
  65.  
  66. LibTool -am Complex.fd
  67.  
  68.   You should see "Complex.i" and "Complex.src". Assemble "Complex.src" as
  69. "LibStart.o".
  70.  
  71.   Link the library as follows
  72.  
  73. blink LibStart.o Complex.o small.lib NODEBUG TO Libs:complex.library
  74.  
  75.   To make a test application, assemble "ComplexApp.asm". Link with a standard
  76. startup code:
  77.  
  78. blink startup.o complexapp.o NODEBUG TO ram:TestProgram
  79.  
  80.   Now run ram:TestProgram.
  81.