@database beginner.guide @Master beginner @Width 75 This is the AmigaGuideŽ file beginner.guide, produced by Makeinfo-1.55 from the input file beginner. @NODE "main" "Modules" @Next "Exceptions.guide/main" @Prev "BuiltIns.guide/main" @Toc "Contents.guide/main" Modules ******* A @{fg shine }module@{fg text } is the E equivalent of a C header file and an Assembly include file. It can contain various object and constant definitions, and also library function offsets and library base variables. This information is necessary for the correct use of a library. A @{fg shine }code module@{fg text } is an extension of the module idea. As well as object and constant definitions, a code module can contain procedures and global variables. Code modules are like C and Assembly object files. @{" Using Modules " Link "Using Modules" } @{" Amiga System Modules " Link "Amiga System Modules" } @{" Non-Standard Modules " Link "Non-Standard Modules" } @{" Example Module Use " Link "Example Module Use" } @{" Code Modules " Link "Code Modules" } @ENDNODE @NODE "Using Modules" "Using Modules" @Next "Amiga System Modules" @Toc "main" Using Modules ============= To use the definitions in a particular module you use the @{b }MODULE@{ub } statement at the beginning of your program (before the first procedure definition). You follow the @{b }MODULE@{ub } keyword by a comma-separated list of strings, each of which is the filename (with path if necessary) of a module (without the @{b }.m@{ub } extension--since every module file name must end with @{b }.m@{ub }). The filenames (and paths) are all relative to the logical volume @{b }Emodules:@{ub } (which can be set-up using an @{b }assign@{ub } as described in the `Reference Manual'), unless the first character of the string is @{b }*@{ub }. In this case the files are relative to the directory of the current source file. For instance, the statement: MODULE 'fred', 'dir/barney', '*mymod' will try to load the files @{b }Emodules:fred.m@{ub }, @{b }Emodules:dir/barney.m@{ub } and @{b }mymod.m@{ub }. If it can't find these files or they aren't proper modules the E compiler will complain. All the definitions in the modules included in this way are available to every procedure in the program. To see what a module contains you can use the @{b }showmodule@{ub } program that comes with the Amiga E distribution. @ENDNODE @NODE "Amiga System Modules" "Amiga System Modules" @Next "Non-Standard Modules" @Prev "Using Modules" @Toc "main" Amiga System Modules ==================== Amiga E comes with the standard Amiga system include files as E modules. The AmigaDOS 2.04 modules are supplied with E version 2.1, and the AmigaDOS 3.0 modules are supplied with E version 3.0. However, modules are much more useful in E version 3.0 (see @{"Code Modules" Link "Code Modules" }). If you want to use any of the standard Amiga libraries properly you will need to investigate the modules for that library. The top-level @{b }.m@{ub } files in @{b }Emodules:@{ub } contain the library function offsets, and those in directories in @{b }Emodules:@{ub } contain constant and object definitions for the appropriate library. For instance, the module @{b }asl@{ub } (i.e., the file @{b }Emodules:asl.m@{ub }) contains the ASL library function offsets and @{b }libraries/asl@{ub } contains the ASL library constants and objects. If you are going to use, say, the ASL library then you need to open the library using the @{b }OpenLibrary@{ub } function (an Amiga system function) before you can use any of the library functions. You also need to define the library function offsets by using the @{b }MODULE@{ub } statement. However, the DOS, Exec, Graphics and Intuition libraries don't need to be opened and their function offsets are built in to E. That's why you won't find, for example, a @{b }dos.m@{ub } file in @{b }Emodules:@{ub }. The constants and objects for these libraries still need to be included via modules (they are not built in to E). @ENDNODE @NODE "Non-Standard Modules" "Non-Standard Modules" @Next "Example Module Use" @Prev "Amiga System Modules" @Toc "main" Non-Standard Modules ==================== Several non-standard library modules are also supplied with Amiga E. To make your own modules you need the @{b }pragma2module@{ub } and @{b }iconvert@{ub } programs. These convert standard format C header files and Assembly include files to modules. The C header file should contain pragmas for function offsets, and the Assembly include file should contain constant and structure definitions (the Assembly structures will be converted to objects). However, unless you're trying to do really advanced things you probably don't need to worry about any of this! @ENDNODE @NODE "Example Module Use" "Example Module Use" @Next "Code Modules" @Prev "Non-Standard Modules" @Toc "main" Example Module Use ================== The gadget example program in Part Three shows how to use constants from the module @{b }intuition/intuition@{ub } (see @{"Gadgets" Link "Examples.guide/Gadgets" }), and the IDCMP example program shows the object @{b }gadget@{ub } from that module being used (see @{"IDCMP Messages" Link "Examples.guide/IDCMP Messages" }). The following program uses the modules for the Reqtools library, which is not a standard Amiga system library but a commonly used one, and the appropriate modules are supplied with Amiga E. To run this program, you will, of course, need the @{b }reqtools.library@{ub } in @{b }Libs:@{ub }. MODULE 'reqtools' PROC main() DEF col IF (reqtoolsbase:=OpenLibrary('reqtools.library',37))<>NIL IF (col:=RtPaletteRequestA('Select a colour', 0,0))<>-1 RtEZRequestA('You picked colour \\d', 'I did|I can\\at remember',0,[col],0) ENDIF CloseLibrary(reqtoolsbase) ELSE WriteF('Could not open reqtools.library, version 37+\\n') ENDIF ENDPROC The @{b }reqtoolsbase@{ub } variable is the library base variable for the Reqtools library. This is defined in the module @{b }reqtools@{ub } and you @{i }must@{ui } store the result of the @{b }OpenLibrary@{ub } call in this variable if you are going to use any of the functions from the Reqtools library. (You can find out which variable to use for other libraries by running the @{b }showmodule@{ub } program on the library module.) The two functions the program uses are @{b }RtPaletteRequestA@{ub } and @{b }RtEZRequestA@{ub }. Without the inclusion of the @{b }reqtools@{ub } module and the setting up of the @{b }reqtoolsbase@{ub } variable you would not be able to use these functions. In fact, if you didn't have the @{b }MODULE@{ub } line you wouldn't even be able to compile the program because the compiler wouldn't know where the functions came from and would complain bitterly. Notice that the Reqtools library is closed before the program terminates (if it had been successfully opened). This is always necessary: if you succeed in opening a library you @{i }must@{ui } close it when you're finished with it. @ENDNODE @NODE "Code Modules" "Code Modules" @Prev "Example Module Use" @Toc "main" Code Modules ============ You can also make modules containing procedure definitions and some global variables. These are called @{fg shine }code modules@{fg text } and can be extremely useful. This section briefly outlines their construction and use. For in-depth details see the `Reference Manual'. Code modules can be made by using the E compiler as you would to make an executable, except you put the statement @{b }OPT MODULE@{ub } at the start of the code. Also, any definitions that are to be accessed from outside the module need to be marked with the @{b }EXPORT@{ub } keyword. Alternatively, all definitions can be exported using @{b }OPT EXPORT@{ub } at the start of the code. You include the definitions from this module in your program using @{b }MODULE@{ub } in the normal way. The following code is an example of a small module: OPT MODULE EXPORT CONST MAX_LEN=20 EXPORT OBJECT fullname firstname, surname ENDOBJECT EXPORT PROC printname(p:PTR TO fullname) IF short(p.surname) WriteF('Hello, \\s \\s\\n', p.firstname, p.surname) ELSE WriteF('Gosh, you have a long name\\n') ENDIF ENDPROC PROC short(s) RETURN StrLen(s)