home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / dirs / libtool_393.lzh / LibTool / CComplex / ComplexC.DOC < prev    next >
Text File  |  1990-10-28  |  4KB  |  86 lines
  1.   This describes how to make the "complex.library" C example. If you have not
  2. made the "simple.library" C 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 VOID. The Init and Open vectors are BOOL
  45. returns. TRUE means that everything went well, and FALSE for an error. If FALSE,
  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 I can keep
  51. track of all of them. I use the address of each task to tag its work buffer.
  52.   Note these 2 functions, OpenUp() and CloseUp() in the file "Complex.c".
  53. Also, note how I set them up in the fd file "ComplexC.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 I 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.   To make the library, compile and assemble "Complex.c" as "Complex.o". Use
  63. LARGE CODE, LARGE DATA. For Manx, we also want +b to eliminate the .begin
  64. statement. Invoke LibTool on "ComplexC.fd" to make our glue code and libstart
  65. code.
  66.  
  67. LibTool -cmho glue.asm ComplexC.fd
  68.  
  69.   You should see "glue.asm", "ComplexC.h", and "ComplexC.src". Assemble
  70. "ComplexC.src" as "LibStart.o" and assemble "glue.asm" as "glue.o".
  71.  
  72.   Link the library as follows
  73.  
  74. blink LibStart.o Complex.o LIB lib:lcnb.lib NODEBUG TO libs:complex.library
  75.  
  76. ln -o libs:complex.library LibStart.o Complex.o -lcl32
  77.  
  78.  
  79.   To make a test application, compile and assemble "ComplexCApp.c". Link as:
  80.  
  81. blink lib:c.o ComplexCApp.o glue.o LIB lib:lcnb.lib NODEBUG TO ram:TestProgram
  82.  
  83. ln -o ram:TestProgram ComplexCApp.o glue.o -lcl32
  84.  
  85.   Now run ram:TestProgram.
  86.