https://wiki.amigaos.net/w/api.php?action=feedcontributions&user=Bill+Borsari&feedformat=atom AmigaOS Documentation Wiki - User contributions [en] 2024-03-29T11:54:50Z User contributions MediaWiki 1.34.0 https://wiki.amigaos.net/w/index.php?title=AmiWest_Lesson_1&diff=8553 AmiWest Lesson 1 2016-08-22T06:11:49Z <p>Bill Borsari: </p> <hr /> <div>= AmiWest Lesson 1: Coding Basics =<br /> <br /> == Compiler and Linker ==<br /> <br /> The [http://gcc.gnu.org/ GNU GCC toolset] is the officially supported standard compiler suite for Amiga operating system programming. An good alternative C compiler named [http://www.compilers.de/vbcc.html vbcc] is also supported and is popular with some programmers. We will focus on GCC which supports both C and C++.<br /> <br /> Some Amiga-specific extensions to the baseline GNU GCC have been made to support the new Exec Interfaces, switching C standard libraries, shared objects and more. The source code for GNU GCC is readily available from the [http://sourceforge.net/projects/adtools/ Amiga Development Tools web site] and you are encouraged to participate if you are able.<br /> <br /> There is a large wealth of detailed documentation and support for GNU GCC and programmers are encouraged to search around the internet. The Amiga-specific extensions are described on the [http://wiki.amigaos.net AmigaOS Documentation Wiki].<br /> <br /> == Standard C Library ==<br /> <br /> AmigaOS officially uses a variant of the [http://sourceware.org/newlib/ Newlib C standard library] implementation. For programmers, it is essential to know what your C standard library is and what its limits are. Functions may or may not be available. Behaviour may or may not be identical between C standard library implementations.<br /> <br /> A popular alternative C standard library implementation is called [http://sourceforge.net/projects/clib2/ clib2] and it is included as an option with the standard Amiga SDK. The clib2 library is particular well suited for porting software from the Unix world. The complete source code for clib2 is also available which makes is possible to debug complex problems involving the C library itself.<br /> <br /> Switching between C standard library is easy thank to an Amiga-specific extension to GCC. The -mcrt option is used for both compiling and linking:<br /> -mcrt=newlib (default, always thread-safe)<br /> -mcrt=clib2 (non-thread safe version)<br /> -mcrt=clib2-ts (thread-safe version)<br /> <br /> == AmigaOS Threading ==<br /> <br /> AmigaOS uses lightweight processes and a shared memory model. As such, it has never been a high priority to provide an Amiga-specific threading implementation.<br /> <br /> That said, the [http://en.wikipedia.org/wiki/POSIX_Threads POSIX threading] API (Pthreads) has been implemented and is available for programmers. This familiar API is quite popular so a lot of software has been written to use it. <br /> <br /> AmigaOS supports a subset of the pthreads standard. It is implemented as a standard shared library with both static and dynamic link interfaces. The dynamic link interface is an Amiga shared object named libpthread.so. The static link interface is available in both newlib and clib2 flavours. These link libraries are just thin wrappers for the underlying pthreads.library which is currently private.<br /> <br /> If your software is AmigaOS-specific then it is fine to launch and control processes using the existing API.<br /> <br /> == Threading in C and C++ ==<br /> <br /> It is very important to note that both C and C++ did not directly support threading until recently. This may come as a surprise to many programmers that have been developing threading applications in both C and C++ for many years.<br /> <br /> Since there was no official standard for so long, threading has always been system dependent and several threading standards have come and gone over the years.<br /> <br /> With C, the threading issue is relatively simple and GNU GCC supports a memory model which has always supported threading so there is little for an Amiga programmer to worry about. This is true for all platforms GCC supports.<br /> <br /> The C++ programming language is a more complicated issue. The current GCC compiler implementation does not support threading on AmigaOS. This can be verified with the g++ -v command. The output of this command will specify what threading model is supported. On AmigaOS it currently states:<br /> <br /> Thread model: single<br /> <br /> This means threading is not supported. As a consequence, C++ exceptions and the RTTI feature will not function correctly in the presence of threads. Both features are optional in C++ but highly desirable. Amiga programmers may need to make some tough decisions in this case.<br /> <br /> == Program Startup ==<br /> <br /> There are two primary environments in which a user can start applications in AmigaOS - by Shell console or by Workbench. Each method comes with its own way of sending the application its starting arguments, data or options.<br /> <br /> With the Workbench, the user can either double-click the application's icon, shift click the app and some other icon(s) or double-click an icon that has this application as its &quot;default tool&quot;.<br /> <br /> In the Shell console, the user usually enters the name of the program and ends the command line with arguments, options and/or a filename.<br /> <br /> In either case, the application typically uses and responds to the files, options and/or arguments that were involved in starting it. A file is opened and/or the program runs as configured.<br /> <br /> === How did your application start? ===<br /> <br /> Following standard ISO C, AmigaOS applications always start using the standard '''argc''' and '''argv''' parameters:<br /> <br /> &lt;syntaxhighlight&gt;<br /> int main(int argc, char **argv)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> The '''argc''' variable indicates the number of arguments received by the application. The first argument ('''argv[0]''') contains the program name. Any following command line arguments are stored in following '''argv''' array elements ('''argv[1]''', '''argv[2]''', ...).<br /> <br /> AmigaOS provides special startup code that fills in the argc and argv parameters for you. The reason for the special startup code is twofold: to setup the standard C library and to support launching programs from Workbench or the Shell.<br /> <br /> In AmigaOS, if ''argc''' is equal to zero that means the application was started from the Workbench. If it is non-zero then it means the application was started from the Shell console.<br /> <br /> While the ISO C method works for applications started from the Shell, it does not directly support an application started from the Workbench. AmigaOS provides ways for handling both Workbench start-up as well as a more sophisticated way of dealing with Shell start-up and arguments.<br /> <br /> === Starting from the Console: the ISO C way ===<br /> <br /> For the sake of ISO C standard conformance, an AmigaOS application can use the standard '''argv''' array variables to read the arguments passed to the app.<br /> <br /> After determining the argument count ('''argc''') is greater than zero, then that number of arguments can be accessed and printed out as follows:<br /> <br /> &lt;syntaxhighlight&gt;<br /> for (int argNo=0; argNo &lt; argc; ++argNo)<br /> {<br /> // print CLI arguments<br /> printf(&quot; argument #%d = &gt;%s&lt;\n&quot;, argNo, argv[argNo]);<br /> }<br /> &lt;/syntaxhighlight&gt;<br /> <br /> This method then leaves the parsing and testing of the arguments to the application and its developer. Many 3rd party libraries are available to parse the arguments such as [http://www.gnu.org/software/libc/manual/html_node/Getopt.html Getopt]. Since we are focusing on AmigaOS-specific programming they won't be discussed any further.<br /> <br /> More information about this topic can be found in [[AmigaDOS_Programming#Running_a_Program_under_the_CLI|Running a Program under the CLI]].<br /> <br /> === Starting from the Console: the AmigaOS way ===<br /> <br /> AmigaOS provides an alternate way for applications to parse arguments from a Shell command line using the '''ReadArgs''' function. In its most common use, this function will parse command line arguments according to a &quot;template&quot; defined by the application. If the user follows the command name with a question mark, this function will print the application's commands template and then allow the user to type in their arguments. If the user fails to provide a valid command line, then '''ReadArgs''' lets the application know and the application can then exit gracefully.<br /> <br /> More information about this topic can be found in [[AmigaDOS_Programming#Standard_Command_Line_Parsing|Standard Command Line Parsing]].<br /> <br /> ==== Configuring ReadArgs ====<br /> <br /> The '''ReadArgs''' function is called with the following syntax:<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct RDArgs *result = IDOS-&gt;ReadArgs(CONST_STRPTR template, int32 *array, struct RDArgs *rdargs);<br /> &lt;/syntaxhighlight&gt;<br /> <br /> The first &quot;template&quot; parameter is a pointer to a string that defines the application's keywords, settings and &quot;toggles&quot; along with the following &quot;modifiers&quot;:<br /> <br /> :* '''/S''' - Switch - indicates keyword string is a boolean setting<br /> :* '''/K''' - Keyword - indicates keyword string must appear before a setting<br /> :* '''/N''' - Number - indicates a setting must be an integer<br /> :* '''/T''' - Toggle - indicates keyword must be followed with a boolean setting (ON, OFF, etc)<br /> :* '''/A''' - Required - indicates keyword must be followed with a value<br /> :* '''/F''' - Rest of line - indicates the rest of the line isn't parsed and taken as one setting<br /> :* '''/M''' - Multiple strings - indicates following strings except for keywords are settings<br /> <br /> Examples of such templates can be found by typing most any AmigaOS command line command with a &quot;?&quot;. Here is an code example of how such a &quot;template&quot; definition could look like:<br /> <br /> &lt;syntaxhighlight&gt;<br /> CONST_STRPTR argTemplate = &quot;TEST/K,NUMBER/K/N,FILE&quot;;<br /> &lt;/syntaxhighlight&gt;<br /> [Note: Make sure there are no spaces in your template!]<br /> <br /> This template allows the user to enter the following optional settings for an application:<br /> <br /> :* the TEST keyword followed with a value.<br /> :* the NUMBER keyword follwed with a numeric value.<br /> :* the FILE keyword and a filename.<br /> <br /> The second parameter in the '''ReadArgs''' function is an array of '''int32''' pointers. If the '''ReadArgs''' function finds valid arguments, the respective array elements will point to any valid user input for those parameters (in template order). To start with, those pointers can be defined and set to NULL values like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> int32 argArray[] =<br /> {<br /> 0,<br /> 0,<br /> 0<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> The final parameter of '''ReadArgs''' function is typically NULL unless the application wants to set some default values (see the DOS/ReadArgs autodocs for more information on this).<br /> <br /> ==== Calling ReadArgs ====<br /> <br /> Once run, the '''ReadArgs''' function will return either a pointer to a '''RDArgs''' structure if it succesfully parsed valid arguments or NULL if inadequate input was provided by the user. If the '''ReadArgs''' function was successful, then each entry of the second parameter (the '''argArray''' defined above) will point to any valid input for that slot in the template.<br /> <br /> It is the developer's choice how best to deal with inadequate input from the user ('''ReadArgs''' returns a NULL value). At the very lest the application should gracefully let the user know the command line arguments were not accepted.<br /> <br /> ====Using ReadArgs Results====<br /> For example, with the above code, the first entry ('''argArray[0]''') would point to any valid input that followed the &quot;TEST&quot; keyword, if it was in the command line. This value could be printed as follows:<br /> <br /> &lt;syntaxhighlight&gt;<br /> if ((int32 *)argArray[0] != NULL)<br /> IDOS-&gt;Printf(&quot; TEST = %s\n&quot;, (STRPTR)argArray[0]);<br /> &lt;/syntaxhighlight&gt;<br /> <br /> If the second &quot;NUMBER&quot; keyword was used with a numeric value, its value could be obtained from the second arguments array entry as follows:<br /> <br /> &lt;syntaxhighlight&gt;<br /> int32 intArg;<br /> if ((int32 *)argArray[1] != NULL)<br /> {<br /> intArg = *(int32 *)argArray[1];<br /> IDOS-&gt;Printf(&quot; NUMBER = %ld\n&quot;, intArg);<br /> }<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ==== Cleaning Up After ReadArgs ====<br /> <br /> If '''ReadArgs''' successfuly parsed input from the command line, the '''FreeArgs''' function must be called using the resulting pointer from '''ReadArgs''' ('''rdargs''' in the above example). This will release any memory used by '''ReadArgs''' to store the user's input, as follows:<br /> <br /> &lt;syntaxhighlight&gt;<br /> IDOS-&gt;FreeArgs(rdargs);<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === Starting from the Workbench: Getting File Names ===<br /> <br /> As discussed above, if the user starts an application from the Workbench, AmigaOS indicates this by setting the '''argc''' variable to ZERO. AmigaOS also uses the '''argv''' variable to send a pointer to a '''WBStartup''' structure that contains more information on the user's actions.<br /> <br /> There are three ways the user could have started an application that will be reflected by the contents of the '''WBStartup''' structure;<br /> <br /> :*'''The user double-clicked on the application's icon''' - In which case the '''WBStartup''' structure will indicate the program's name and &quot;lock&quot; its directory location on disk.<br /> <br /> :*'''The user double-clicked on the &quot;project&quot; file's icon that had this application set as its &quot;tool&quot;''' - In addition to the app's information, the '''WBStartup''' structure will indicate the project file's name and &quot;lock&quot; the project file's directory.<br /> <br /> :*'''The user selected one (or more) &quot;project&quot; files and shift-double-clicked on the application's icon''' - The '''WBStartup''' structure will have a file name and directory &quot;lock&quot; for each of the project files in addition to the application's information.<br /> <br /> In all these cases, when the application starts, it must goes though a few steps to determine if any files were selected with it. If the application also wants to read any settings attached to those files - as &quot;Tool Types&quot; within their icons - the application has to go through a few more steps. These steps start with reading the '''WBStartup''' structure passed to the app.<br /> <br /> More information about this topic can be found in [[Workbench_and_Icon_Library#Workbench_Environment|Workbench Environment]] and<br /> [[Workbench_and_Icon_Library#Workbench_and_the_Startup_Code_Module|Workbench and Startup Code]].<br /> <br /> ==== Accessing the WBStartup structure ====<br /> <br /> When started by the Workbench, an application is passed a pointer to the '''WBStartUp''' structure in the standard '''argv''' variable. After checking the '''argc''' variable is equal to zero (to see that it was started by the Workbench), the '''WBStartUp'' structure can be obtained like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> if (argc == 0)<br /> {<br /> struct WBStartup *wbs = (struct WBStartup *)argv;<br /> }<br /> &lt;/syntaxhighlight&gt;<br /> <br /> The '''WBStartup''' structure is based on the AmigaOS '''Message''' structure and it has the following format:<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct WBStartup<br /> {<br /> struct Message sm_Message; /* a standard message structure */<br /> struct MsgPort * sm_Process; /* the process descriptor for you */<br /> BPTR sm_Segment; /* a descriptor for your code */<br /> int32 sm_NumArgs; /* the number of elements in ArgList */<br /> char * sm_ToolWindow; /* reserved for future use */<br /> struct WBArg * sm_ArgList; /* the arguments themselves */<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Under typical circumstances the '''sm_NumArgs''' and '''sm_ArgList''' are the only elements of the structure that need to be accessed for program start up. The number of arguments will always be at least one, with the first entry representing the application itself. Any number of arguments above one reflects the number of &quot;project&quot; files or icons the user selected when the application was started.<br /> <br /> The '''sm_ArgList''' will be an array of '''WBArg''' structures where the number of elements corresponds to the number of application &amp; data files selected by the user (reflected by the '''sm_NumArgs''' variable above). The '''WBArg''' structure containing the arguments has the following format:<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct WBArg<br /> {<br /> BPTR wa_Lock; /* a lock descriptor */<br /> STRPTR * wa_Name; /* a string relative to that lock */<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> The '''wa_Lock''' contains a pointer to an AmigaOS &quot;lock&quot; on the directory containing that argument's application or data file. For each of the files (the application or project files) passed to the application from the Workbench, a &quot;lock&quot; is applied to that directory. This prevents the directory of the application or any of the selected data files (&quot;projects&quot;) from being disturbed or deleted while they are in use. <br /> <br /> The '''wa_Name''' contains a string pointer to the name of the application or data file. This is a pointer to the name of the file itself and doesn't include the pathname for the directory is stored in.<br /> <br /> The names of the application and any selected files could be printed out with the following code excerpt:<br /> <br /> &lt;syntaxhighlight&gt;<br /> uint8 NoArgs, argNo;<br /> NoArgs = wbs-&gt;sm_NumArgs;<br /> IDOS-&gt;Printf(&quot; number of args received = %ld\n&quot;, NoArgs);<br /> for (argNo = 0; argNo &lt; NoArgs; ++argNo)<br /> IDOS-&gt;Printf(&quot; arg %ld name = &gt;%s&lt;\n&quot;, argNo, wbs-&gt;sm_ArgList[argNo].wa_Name);<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Below we will see how to obtain more information from the selected files and how to get full path names for each. When the application finishes running, AmigaOS will release the &quot;locks&quot; on the directories referred to by the '''WBStartUp''' entries.<br /> <br /> === WorkBench StartUp: Examining Icons &amp; Tooltypes ===<br /> <br /> Whereas options might be given to a program in the Shell console in the form of argument in command line, Workbench programs frequently keep such settings within the application's icon, which is stored in a companion '''.info''' file. Specifically, each icon has the ability to store &quot;Tool Types&quot; text strings within the icon's .info file. While such settings can be almost any form of text, the standard format is to have a SETTING, equals sign and a value, like these: <br /> <br /> &lt;pre&gt;<br /> TEST=verbose<br /> NUMBER=23<br /> &lt;/pre&gt;<br /> <br /> These &quot;Tool Type&quot; settings are usually stored within the application's icon, but such settings can be also stored in most any icon files in AmigaOS. As such, an application can also look for such information within each project's icon file.<br /> <br /> For an application to access any information that might be stored in its icon's '''.info''' file or in those of the &quot;Projects&quot; passed to the application, the application needs to go through a few more steps after collecting the related file names (mentioned above).<br /> <br /> More information about this topic can be found in [[Workbench_and_Icon_Library#The_Tool_Types_Array|Tool Types Array]].<br /> <br /> ==== Getting to Each Icon's Directory ====<br /> <br /> The easiest way to access any of the files sent by the Workbench is to use the '''sm_ArgList''' entry provided for each. This is done by first confirming a valid directory was found and &quot;locked&quot; for us by the Workbench. Then we call the '''CurrentDir''' function to switch the application to that directory, like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> if (wbs-&gt;sm_ArgList[argNo].wa_Lock != ZERO)<br /> {<br /> BPTR oldDir = IDOS-&gt;CurrentDir(wbs-&gt;sm_ArgList[argNo].wa_Lock);<br /> }<br /> &lt;/syntaxhighlight&gt;<br /> <br /> As you can see, this function returns a pointer to the old directory when we switch to the new directory location. This is very important, since the Workbench also maintains a directory lock based on the application's current directory. Before an application finishes, it needs to call the '''CurrentDir''' function again and switch back to the application's original location so it can be &quot;unlocked&quot; when the app quits - like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> IDOS-&gt;CurrentDir(oldDir);<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ==== Getting Icon Information ====<br /> <br /> Once the application has &quot;moved&quot; to the directory of the icon file to be examined, we can use the '''GetDiskObjectNew''' function to get information from the icon. This function is simply called using the same '''wa_Name''' element from the '''sm_ArgList''' structure used above, as in this code excerpt:<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct DiskObject *dobj;<br /> dobj = IIcon-&gt;GetDiskObjectNew(wbs-&gt;sm_ArgList[argNo].wa_Name);<br /> if(dobj != NULL)<br /> {<br /> IDOS-&gt;Printf(&quot; Opened disk object.\n&quot;);<br /> }<br /> &lt;/syntaxhighlight&gt;<br /> <br /> The '''GetDiskObjectNew''' function automatically appends the &quot;.info&quot; necessary to open the selected file's icon. If there is no .info file for the selected file, this function will automatically use the information from the &quot;default icon&quot; for the selected file type. For example, if the file &quot;test.jpg&quot; has no &quot;test.jpg.info&quot; icon file, the &quot;def_jpeg.info&quot; will be used.<br /> <br /> If an application needs to explore icon information for a file not in the current directory of the app, the '''GetDiskObjectNew''' function will also accept the name of a file including a full path. But as we will see below, this does involve the application going through the overhead of allocating a string sufficient to store the full file &amp; path name.<br /> <br /> If successful, the '''GetDiskObjectNew''' function returns a pointer to a '''DiskObject''' structure that provides the following information for that '''.info''' file and icon:<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct DiskObject<br /> {<br /> UWORD do_Magic; /* magic number at start of file */<br /> UWORD do_Version; /* so we can change structure */<br /> struct Gadget do_Gadget; /* a copy of in core gadget */<br /> UBYTE do_Type;<br /> char *do_DefaultTool;<br /> char **do_ToolTypes;<br /> LONG do_CurrentX;<br /> LONG do_CurrentY;<br /> struct DrawerData *do_DrawerData;<br /> char *do_ToolWindow; /* only applies to tools */<br /> LONG do_StackSize; /* only applies to tools */<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> As you can see, the '''DiskObject''' structure presents most of the information conveyed by an AmigaOS icon. The '''do_DefaultTool''' is the setting that is used to designate whichever application will be used when a &quot;Project&quot; icon is double-clicked. The '''do_ToolTypes''' element points to an array of strings containing the icon's &quot;Tool Types&quot;.<br /> <br /> ==== Checking for Our Tooltypes ====<br /> <br /> AmigaOS provides another function to simplify checking the Tool Types for values an application is interested in - the '''FindToolType''' function. It is simply called with the pointer to the '''do_ToolTypes''' array and the desired setting string. This function returns either a pointer to the string with that ToolType setting or NULL if the ToolType wasn't found. The following code would check for our &quot;TEST&quot; ToolType and print out any results found.<br /> <br /> &lt;syntaxhighlight&gt;<br /> STRPTR TTarg = NULL;<br /> TTarg = IIcon-&gt;FindToolType(dobj-&gt;do_ToolTypes, &quot;TEST&quot;);<br /> if (TTarg)<br /> IDOS-&gt;Printf(&quot; TEST found set to = &gt;%s&lt;\n&quot;, TTarg);<br /> &lt;/syntaxhighlight&gt;<br /> <br /> With all the above code, an application can check each of the elements of the '''sm_ArgList''' sent by the Workbench to check for Tool Types in the app's icon as well as any of the icons of any Project files sent to the app.<br /> <br /> === Workbench StartUp: Getting Path &amp; File Names ===<br /> <br /> So far the above code has relied on using the '''WBStartUp''' structure and '''sm_ArgList''' sub-structure to obtain the necessary information on the application and any Project files selected. This has avoided directly dealing with the full file and path names of those files. If the full file &amp; path name is required, the application can get the full path name by examining the directory &quot;lock&quot; of each '''sm_ArgList''' entry. This is done by calling the DOS '''NameFromLock''' function with another multi-step process.<br /> <br /> First we must allocate a string in which to put the full name, then call '''NameFromLock''' to get the path name from the &quot;Lock&quot; and finally we must free the allocated memory after we're done with it. The following code excerpt would obtain the path to the application (always the first entry in '''sm_ArgList'''):<br /> <br /> &lt;syntaxhighlight&gt;<br /> int32 StringLen = 2048;<br /> // Alloc memory for pathname string<br /> filename = (STRPTR) IExec-&gt;AllocVecTags(StringLen, TAG_END);<br /> if (filename)<br /> {<br /> if (wbs-&gt;sm_ArgList[0].wa_Lock != ZERO)<br /> if (IDOS-&gt;NameFromLock(wbs-&gt;sm_ArgList[0].wa_Lock,filename, StringLen) != 0)<br /> IDOS-&gt;Printf(&quot; app path name = &gt;%s&lt;\n&quot;, filename);<br /> // deallocate pathname string memory<br /> IExec-&gt;FreeVec(filename);<br /> }<br /> &lt;/syntaxhighlight&gt;<br /> <br /> As you can see, we allocate a large string size for the path name - 2048 characters - to provide room for potentially long and/or heavily nested path names. If that string is not long enough, the '''NameFromLock''' function will fail and return a NULL value. The developer must use their judgment in deciding how likely this error might be and how much effort to put into handling it - whether to have the application politely handle and notify the user of the error or whether to wrap this function in some loop that keeps allocating larger string sizes until '''NameFromLock''' succeeds.<br /> <br /> Obviously, there are few levels of error trapping in this code: to make sure we were able to allocate our string ('''filename'''), to make sure there is a valid directory lock to use and finally to make sure the path name could be obtained from the lock. Regardless of how unlikely failure might be, within any application these tests should occur and be &quot;wrapped&quot; in proper and graceful error handling and feedback.<br /> <br /> ==== Getting The Full Name ====<br /> <br /> Once we have the path name, we can combine that with the name of the file (from the '''wa_Name''' element of the '''sm_ArgList''' structure). AmigaOS provides the '''AddPart''' function which also resolves AmigaOS separator characters (&quot;/&quot; or &quot;:&quot;) to create a valid and complete file pathname, like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> if (IDOS-&gt;AddPart(filename,wbs-&gt;sm_ArgList[argNo].wa_Name,StringLen) != 0)<br /> IDOS-&gt;Printf(&quot; full path = &gt;%s&lt;\n&quot;, filename);<br /> &lt;/syntaxhighlight&gt;<br /> <br /> The resulting combined path and file name should be suitable for use by the application - to open or act upon the file selected by the user. <br /> <br /> Bear in mind, we are still working within the fixed size of the &quot;filename&quot; string that must contain both the path name as well as the file name. As before, we use error trapping to check that the combined file and path names fit into the string length we've defined. Again, should there be a failure, provide feedback and gracefully manage the situation.<br /> <br /> === Example Program Source Code ===<br /> <br /> The following is an example program to demonstrate the above concepts in starting an application from the Shell and the Workbench.<br /> <br /> From the Shell, the user can enter arguments or enter the &quot;?&quot; to see the template prompt before entering arguments. Commented out within the code<br /> is a working example of using the simple ANSI method of reading command line arguments.<br /> <br /> From the Workbench, this example will print out all the above information found on all the arguments passed by the Workbench. Besides the application's information, the printed information will reflected selected icons or Projects calling this app as a default Tool.<br /> <br /> An archive for use with CodeBench is available [[Media:ArgParser.lha|from here]].<br /> <br /> &lt;syntaxhighlight&gt;<br /> /*<br /> ************************************************************<br /> **<br /> ** Created by: CodeBench 0.26 (04.01.2012)<br /> **<br /> ** Project: PJS-OS4ex-StartUp<br /> **<br /> ** Version: 4<br /> **<br /> ** File: This an example program of the various AmigaOS<br /> ** ways of starting an application - from CLI or<br /> ** Workbench - and dealing with the options.<br /> **<br /> ** Date: 25-08-2012 18:21:44<br /> **<br /> ************************************************************<br /> */<br /> <br /> #include &lt;exec/execbase.h&gt;<br /> #include &lt;workbench/startup.h&gt;<br /> <br /> #include &lt;proto/exec.h&gt;<br /> #include &lt;proto/dos.h&gt;<br /> #include &lt;proto/icon.h&gt;<br /> <br /> #include &lt;string.h&gt;<br /> #include &lt;stdio.h&gt;<br /> <br /> // declare &amp; initialize empty LONG words array to be filled with pointers to CLI arguments received<br /> int32 argArray[] =<br /> {<br /> 0,<br /> 0,<br /> 0<br /> };<br /> <br /> // declare the number of possible arguments (the size of the argArray above)<br /> uint8 noArgs = 3;<br /> <br /> // declare CLI options template string with these modifiers:<br /> // /S - Switch - indicates keyword string is a boolean setting<br /> // /K - Keyword - indicates keyword string must appear before a setting<br /> // /N - Number - indicates a setting must be an integer<br /> // /T - Toggle - indicates keyword must be followed with a boolean setting (ON, OFF, etc)<br /> // /A - Required - indicates keyword must be followed with a value<br /> // /F - Rest of line - indicates the rest of the line isn't parsed and taken as one setting<br /> // /M - Multiple strings - indicates following strings except for keywords are settings<br /> //<br /> CONST_STRPTR argTemplate = &quot;TEST/K,NUMBER/K/N,FILE&quot;;<br /> <br /> uint8 returnCode = RETURN_OK;<br /> <br /> // Starting program<br /> int main(int argc,char **argv)<br /> {<br /> uint8 argNo;<br /> <br /> IDOS-&gt;Printf(&quot;AmigaOS StartUp Example\n&quot;);<br /> <br /> // Check if program was started from CLI or Workbench based on value of &quot;argc&quot;<br /> if (argc &gt; 0)<br /> {<br /> IDOS-&gt;Printf(&quot;Started from CLI.\n&quot;);<br /> <br /> // declare struct pointer to receive CLI options<br /> struct RDArgs *rdargs;<br /> <br /> // read CLI args (using AmigaOS method)<br /> rdargs=IDOS-&gt;ReadArgs(argTemplate,argArray,NULL);<br /> <br /> // were CLI arguments sucessfully read?<br /> if (rdargs)<br /> {<br /> int32 intArg;<br /> <br /> // loop through possible options &amp; settings and print them<br /> for (argNo=0; argNo&lt;noArgs; ++argNo)<br /> {<br /> // print readarg arguments<br /> IDOS-&gt;Printf(&quot; arg %ld = %s\n&quot;, argNo, argArray[argNo]);<br /> if ((int32 *)argArray[argNo] != NULL)<br /> {<br /> intArg = *(int32 *)argArray[argNo];<br /> IDOS-&gt;Printf(&quot; # = &gt;%ld&lt;\n&quot;, intArg);<br /> }<br /> }<br /> <br /> // free memory used by ReadArgs and data<br /> IDOS-&gt;FreeArgs(rdargs);<br /> }<br /> else<br /> IDOS-&gt;Printf(&quot; ERROR: Incorrect Values received by ReadArgs\n&quot;);<br /> <br /> //read args using ISO C method<br /> /*<br /> for (argNo=0; argNo&lt;argc; ++argNo)<br /> {<br /> // print CLI arguments<br /> IDOS-&gt;Printf(&quot; argument #%ld = &gt;%s&lt;\n&quot;, argNo, argv[argNo]);<br /> }<br /> */<br /> }<br /> else<br /> {<br /> IDOS-&gt;Printf(&quot;Started from Workbench.\n&quot;);<br /> <br /> // set pointer to WBStartUp structure using argv contents<br /> struct WBStartup *wbs = (struct WBStartup *)argv;<br /> <br /> // set a length for path names (to be added to file name length)<br /> int32 MaxPathLen = 1792;<br /> // set a length for file names (to be added to path name length)<br /> int32 MaxFileLen = 256;<br /> <br /> // working variable<br /> uint8 NoArgs;<br /> STRPTR filename = NULL;<br /> STRPTR TTarg = NULL;<br /> BPTR oldDir = ZERO;<br /> <br /> // print out number of arguments (first one is this program)<br /> NoArgs = wbs-&gt;sm_NumArgs;<br /> IDOS-&gt;Printf(&quot; number of args received = %ld\n&quot;, NoArgs);<br /> <br /> // Alloc memory for pathname string<br /> filename = (STRPTR) IExec-&gt;AllocVecTags(MaxPathLen+MaxFileLen, TAG_END);<br /> <br /> // Alloc disk object pointer for icon information<br /> struct DiskObject *dobj;<br /> <br /> if (filename)<br /> {<br /> // loop through WB arguments getting path names<br /> for (argNo=0; argNo&lt;NoArgs; ++argNo)<br /> {<br /> IDOS-&gt;Printf(&quot; arg %ld name = &gt;%s&lt;\n&quot;, argNo, wbs-&gt;sm_ArgList[argNo].wa_Name);<br /> <br /> if (wbs-&gt;sm_ArgList[argNo].wa_Lock != ZERO)<br /> {<br /> IDOS-&gt;Printf(&quot; file locked.\n&quot;);<br /> <br /> // CD to project file's dir<br /> oldDir = IDOS-&gt;CurrentDir(wbs-&gt;sm_ArgList[argNo].wa_Lock);<br /> <br /> // get disk object on argument's file<br /> dobj = IIcon-&gt;GetDiskObjectNew(wbs-&gt;sm_ArgList[argNo].wa_Name);<br /> if(dobj)<br /> {<br /> IDOS-&gt;Printf(&quot; Opened disk object.\n&quot;);<br /> <br /> // check for &quot;TEST&quot; keyword<br /> TTarg = IIcon-&gt;FindToolType(dobj-&gt;do_ToolTypes, &quot;TEST&quot;);<br /> if (TTarg)<br /> IDOS-&gt;Printf(&quot; TEST found set to = &gt;%s&lt;\n&quot;,TTarg);<br /> else<br /> IDOS-&gt;Printf(&quot; TEST tooltype not found.\n&quot;);<br /> <br /> // check for &quot;NUMBER&quot; keyword<br /> TTarg = IIcon-&gt;FindToolType(dobj-&gt;do_ToolTypes, &quot;NUMBER&quot;);<br /> if (TTarg)<br /> IDOS-&gt;Printf(&quot; NUMBER found set to = &gt;%s&lt;\n&quot;,TTarg);<br /> else<br /> IDOS-&gt;Printf(&quot; NUMBER tooltype not found.\n&quot;);<br /> <br /> // free disk object structure &amp; memory<br /> IIcon-&gt;FreeDiskObject(dobj);<br /> }<br /> else<br /> {<br /> // print why we couldn't get icon information<br /> int32 MYerror, MYerrLen;<br /> MYerror = IDOS-&gt;IoErr();<br /> IDOS-&gt;Printf(&quot; ERROR: Unable to open disk object.\n&quot;);<br /> IDOS-&gt;Printf(&quot; number = &gt;%ld&lt;\n&quot;,MYerror);<br /> MYerrLen = IDOS-&gt;Fault(MYerror,NULL,filename,80);<br /> IDOS-&gt;Printf(&quot; text = &gt;%s&lt;\n&quot;,filename);<br /> returnCode = RETURN_ERROR;<br /> }<br /> <br /> // CD back to previous dir<br /> IDOS-&gt;CurrentDir(oldDir);<br /> <br /> // Indicate what type of file the WBArg is refering to<br /> if (argNo == 0)<br /> IDOS-&gt;Printf(&quot; entry = application.\n&quot;);<br /> else<br /> {<br /> // check item type<br /> if (strlen(wbs-&gt;sm_ArgList[argNo].wa_Name) &gt; 0)<br /> IDOS-&gt;Printf(&quot; entry = file.\n&quot;);<br /> else<br /> IDOS-&gt;Printf(&quot; entry = device or directory.\n&quot;);<br /> }<br /> <br /> // Get the path and full path/filename of the file<br /> if (IDOS-&gt;NameFromLock(wbs-&gt;sm_ArgList[argNo].wa_Lock,filename,MaxPathLen) != 0)<br /> {<br /> IDOS-&gt;Printf(&quot; path name = &gt;%s&lt;\n&quot;,filename);<br /> <br /> if (IDOS-&gt;AddPart(filename,wbs-&gt;sm_ArgList[argNo].wa_Name,MaxPathLen+MaxFileLen) != 0)<br /> IDOS-&gt;Printf(&quot; full path = &gt;%s&lt;\n&quot;,filename);<br /> else<br /> {<br /> IDOS-&gt;Printf(&quot; ERROR: full name is larger than %ld\n&quot;,(MaxPathLen+MaxFileLen));<br /> returnCode = RETURN_WARN;<br /> }<br /> }<br /> else<br /> {<br /> IDOS-&gt;Printf(&quot; ERROR: path name is larger than %ld\n&quot;,MaxPathLen);<br /> returnCode = RETURN_WARN;<br /> }<br /> <br /> }<br /> else<br /> {<br /> IDOS-&gt;Printf(&quot; ERROR: file handle could not be locked.\n&quot;);<br /> returnCode = RETURN_ERROR;<br /> }<br /> }<br /> <br /> // deallocate pathname string memory<br /> IExec-&gt;FreeVec(filename);<br /> }<br /> else<br /> {<br /> IDOS-&gt;Printf(&quot; ERROR: unable to allocate memory for string!\n&quot;);<br /> returnCode = RETURN_ERROR;<br /> }<br /> }<br /> <br /> IDOS-&gt;Printf(&quot;GOODBYE!\n&quot;);<br /> return (returnCode);<br /> }<br /> &lt;/syntaxhighlight&gt;</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=AmigaOS_Manual:_AmigaDOS_Additional_Amiga_Directories&diff=7422 AmigaOS Manual: AmigaDOS Additional Amiga Directories 2014-04-04T22:37:00Z <p>Bill Borsari: /* Creating a MountFile or MountList Entry */</p> <hr /> <div>In addition to the AmigaDOS commands, there are other files and directories on your Workbench disk. This chapter includes the following:<br /> <br /> * DEVS:<br /> * S:<br /> * L:<br /> * FONTS:<br /> * LIBS:<br /> * REXX:<br /> * LOCALE:<br /> * ENVARC:<br /> * ENV:<br /> * CLIPS:<br /> * T:<br /> * Classes<br /> * C:<br /> <br /> The drawers contained in DEVS: are described in the Workbench User's Guide .<br /> <br /> You do not need a detailed understanding of the contents of the directories listed here. Unless specifically directed otherwise, you can safely ignore them. However, you should know their purposes and locations in case you inadvertently delete or rename a file in a directory or need to copy something to the appropriate directory.<br /> <br /> Figure B-1 illustrates the standard directory structure of a hard disk Amiga system. Directories with icons visible from Workbench (drawers) are shown on the left; other directories are on the right. The standard contents and structure of these directories may change as Commodore adds, changes, or removes resources.<br /> <br /> [[File:DosFigB-1.png|center|frame|System Directory Tree]]<br /> <br /> Most of these directories are automatically assigned to the SYS: volume or to the Ram Disk. These directories, as well as SYS:, can be ASSIGNed to different volume when necessary.<br /> <br /> For example, you can assign FONTS: to a particular disk, such as FontDisk:. Most applications automatically look for the fonts that they need in the FONTS: directory, regardless of where that is. By changing the FONTS: assignment, you can allow applications to use the fonts on FontDisk:<br /> <br /> = DEVS: =<br /> <br /> In addition to the DOSDrivers, Keymaps, Printers, Monitors, and DataTypes drawers described in the Workbench User's Guide, the DEVS: drawer contains files and subdirectories that pertain to the devices that can be used with the Amiga.<br /> <br /> Note that you can refer to the DEVS:Keymaps and DEVS:Printers drawers by their assigned names KEYMAPS: and PRINTERS:, respectively.<br /> <br /> == Device Files ==<br /> <br /> The following lists the .device files in DEVS: and their functions:<br /> <br /> {| class=&quot;wikitable&quot;<br /> | clipboard.device || Controls access to CLIPS:.<br /> |-<br /> | Parallel.device || Controls access to the parallel port.<br /> |-<br /> | printer.device || Controls access to the printer device.<br /> |-<br /> | Serial.device || Controls access to the serial port.<br /> |-<br /> | mfm.device || Controls access to MS-DOS disks with CrossDOS.<br /> |}<br /> <br /> For more information on the .device files, see [[Devices|Amiga Devices]].<br /> <br /> == Other Files ==<br /> <br /> The following additional files are found in DEVS:<br /> <br /> {| class=&quot;wikitable&quot;<br /> | system-configuration || Holds certain Preferences configuration data needed when booting.<br /> |-<br /> | Postscript_init.ps || Holds information needed to initialize a PostScript printer when using PrinterPS.<br /> |}<br /> <br /> === Using Mount Files or a MountList ===<br /> <br /> To access new devices, the Amiga must be informed when any are added. These may be physical devices, such as a tape drive, or software (logical) devices, such as a recoverable RAM disk. There are several ways to do this:<br /> <br /> * Placing a driver in the Expansion drawer<br /> * Placing a mount file in the DOSDrivers drawer<br /> * Making an entry for the device in a MountList file and using the MOUNT command<br /> <br /> A mount file represents a device, handler, or file system. Standard devices have their own mount file with icons in the DOSDrivers drawer in DEVS:. These are mounted automatically during the standard Startup-sequence. Alternatively, devices can use the MOUNT command to read a MountList entry that determines the characteristics of the device.<br /> <br /> The need to use a MountList and the MOUNT command has been eliminated by the mount file method used in Amiga system software Release 2.1 and beyond. Rather than requiring a MountList file with entries for each device you want to mount, DEVS: now contains the DOSDrivers drawer, which holds a separate mount file or DOS driver for each device. The contents of a mount file are essentially the same as an individual MountList entry.<br /> <br /> You can, however, continue to use a MountList to mount devices. Copy the MountList to DEVS: and remove any DOS drivers in the DOSDrivers drawers that have the same name as one of your MountList entries. (A mount file overrides a MountList entry of the same name.)<br /> <br /> === Creating a MountFile or MountList Entry ===<br /> <br /> The following information on mount files also applies to MountLists, except as noted.<br /> <br /> Mount files contain keywords describing the device, handler, or file system, as well as values for those keywords. Some keywords apply only to a filesystem or a handler. If a keyword is omitted, a default value is used. Be sure that the default value is appropriate for the device.<br /> <br /> The following are rules for creating a mount file or MountList:<br /> <br /> * The file must be a plain ASCII text file.<br /> * The mount file name must be the name of the device; the name of a MountList should be MountList.<br /> * Each entry in a MountList must start with the name of the device. Omit this for a mount file.<br /> * Keywords are followed by an equals sign (=).<br /> * Keywords must be separated by a semicolon or be placed on separate lines.<br /> * Comments are allowed in standard C style (that is, comments start with /* and end with */).<br /> * Each MountList entry must end with the # symbol. Omit this for a mount file.<br /> <br /> When creating a new mount file or MountList entry, refer to the documentation that came with the device or start with an example of one for a similar device. Change or add only the necessary keywords.<br /> <br /> The following table, lists keywords and their default values supported in a mount file or MountList and their functions. Default values are shown in angle brackets.<br /> <br /> {| class=&quot;wikitable&quot;<br /> ! Keyword !! Function <br /> |-<br /> | Handler=&lt;none&gt; || A handler entry (for example, Handler = L:eque-handler).<br /> |-<br /> | Ehandler=&lt;none&gt; || An environment handler entry.<br /> |-<br /> | FileSystem=&lt;none&gt; || A file system entry (for example, FileSystem = L:CrossDosFileSystem).<br /> |-<br /> | Device=&lt;none&gt; || A device entry (for example, Device = DEVS:mfm.device). This argument is required to mount a file system. There is no default value for Device; you must supply a value.<br /> |-<br /> | Priority=&lt;10&gt; || The priority of the process; 5 is good for handlers, 10 for file systems.<br /> |-<br /> | Unit=&lt;0&gt; || The unit number of the device (for example, 0 for PC0:).<br /> |-<br /> | Flags=&lt;0&gt; || Flags for OpenDevice (usually 0).<br /> |-<br /> | Surfaces=&lt;none&gt; || The numbner of surfaces (2 for floppy devices, varies for hard drives). This argument is required to mount a file system. There is no default value for Surfaces; you must supply a value.<br /> |-<br /> | SectorsPerBlock=&lt;none&gt; || Defines the number of physical disk sectors in each logical block used by the file system.<br /> |-<br /> | SectorsPerTrack=&lt;none&gt; || The number of blocks per track. This argument is required to mount a file system. There is no default value for SectorsPerTrack; you must supply a value.<br /> |-<br /> | SectorSize=&lt;512&gt; || Specifies the number of bytes in a block on the device. Most devices use a 512 byte block; however, some devices use other sizes (for example, CD-ROMs use 2048 bytes).<br /> |-<br /> | Reserved=&lt;2&gt; || The number of blocks reserved for the boot block; should be 2.<br /> |-<br /> | Interleave=&lt;0&gt; || Interleave value; varies with the device.<br /> |-<br /> | LowCyl=&lt;none&gt; || Starting cylinder to use. This argument is required to mount a file system. There is no default value for LowCyl; you must supply a value.<br /> |-<br /> | HighCyl_&lt;none&gt; || Ending cylinder to use. This argument is required to mount a file system. There is no default value for HighCyl; you must supply a value.<br /> |-<br /> | Stacksize=&lt;600&gt; || Amount of stack allocated to the process.<br /> |-<br /> | Buffers=&lt;5&gt; || Number of initial 512-byte cache buffers. Increase this for higher disk performance if you have RAM to spare.<br /> |-<br /> | BufMem Type=&lt;3&gt; || Memory type used for buffers; (0 and 1 = Any, 2 and 3 = Chip, 4 and 5 = Fast).<br /> |-<br /> | Mount=&lt;0&gt; || See the description of ACTIVATE, which is a synonym for MOUNT.<br /> |-<br /> | MaxTransfer=&lt;0x7ffffff&gt; || The maximum number of bytes transferred at one time with any file system. Use Max Transfer for compatibility with older hard drive systems.<br /> |-<br /> | Mask=&lt;0xffffffff&gt; || Address Mask to specify memory range that DMA transfers can use at one time with any file system. Use Mask for compatibility with older hard drive systems.<br /> |-<br /> | Glob Vec=&lt;2&gt; || A global vector for the process; -1 is no Global Vector (for C and assembler programs), 0 sets up a private GV; if the keyword is absent, the shared Global Vector is used. Omit this keyword for Amiga file system devices.<br /> |-<br /> | Startup=&lt;none&gt; || A string passed to the device, handler, or file system on startup as a BPTR to a BSTR.<br /> |-<br /> | Activate=&lt;0&gt; || If a positive value, ACTIVATE loads the device or handler immediately rather than waiting for first access. Synonymous with MOUNT.<br /> |-<br /> | BootPri=&lt;0&gt; || A value that sets the boot priority of a bootable and mountable device. This value can range from -129 to 127. By convention, -129 indicates that the device is not bootable and is not automatically mounted.<br /> |-<br /> | DosType=&lt;0x444F5300&gt; || Indicates the type of file system, giving hexadecimal ASCII codes for three letters and a concluding number as follows:<br /> {| class=&quot;wikitable&quot;<br /> ! Value !! ASCII !! File System<br /> |-<br /> | 0x444F5300 || DOS0 || Original (OFS)<br /> |-<br /> | 0x444F5301 || DOS1 || FastFileSystem (FFS)<br /> |-<br /> | 0x444F5302 || DOS2 || International Mode OFS<br /> |-<br /> | 0x444F5303 || DOS3 || International Mode FFS<br /> |-<br /> | 0x444F5304 || DOS4 || Directory caching International Mode OFS<br /> |-<br /> | 0x444F5305 || DOS5 || Directory caching International Mode FFS<br /> |-<br /> | 0x4D534400 || MSD0 || MS-DOS<br /> |}<br /> |-<br /> | Baud=&lt;1200&gt; || Serial device baud rate.<br /> |-<br /> | Control=&lt;0&gt; || Serial device word length, parity, and stop bits.<br /> |-<br /> | Forceload=&lt;0&gt; || Forces a file system to be loaded form disk even though a suitable entry is in the resource list. If 0 (the default), check the resource list before the disk. If 1, always load from disk.<br /> |}<br /> <br /> = S: Directory =<br /> <br /> The S: directory is generally reserved for AmigaDOS and ARexx scripts. However, you may place non-script files in S: or place script files in other directories. In addition to the Startup-sequence file, the User-startup file that you create, and Shell-startup files, the S: directory also contains teh scripts described in this section.<br /> <br /> == ED-Startup ==<br /> <br /> This file contains ED commands used to configure the ED text editor, assigning the default function key options. Key assignments can be customized by editing this file. Removing or renaming this file activates expanded ED command menus; see Chapter 4 for instructions on how to do this.<br /> <br /> Other files containing ED commands can be stored in S: for use by the WITH keyword of ED, which allows ED command files to perform custom editing operations.<br /> <br /> == SPat, DPat ==<br /> <br /> These scripts allow pattern matching with commands that do not normally support it. When run with a command, SPat and DPat use the LIST command to create temporary script files in the T: directory and then execute the scripts. SPat and DPat can be used within command aliases.<br /> <br /> SPat adds pattern matching to single-argument commands. For example, to use ED to edit all the files in the S: directory beginning with the letter's, enter:<br /> <br /> 1&gt; SPat ED S:s#?<br /> <br /> A script similiar to the following is generated:<br /> <br /> ED &quot;s:Shell-startup&quot;<br /> ED &quot;s:SPat&quot;<br /> ED &quot;s:Startup-sequence&quot;<br /> <br /> SPat executes the script, invoking ED three times to display the files.<br /> <br /> DPat adds pattern matching to double-argument commands. After DPat and the command name, enter the two arguments separated by a space, using the wildcards required to produce the desired matches.<br /> <br /> == PCD ==<br /> <br /> Like the CD command, the PCD script changes the current directory. However, PCD also remembers the directory from which you are changing, so you can return to it without entering the entire path. Each Shell has an independent PCD memory.<br /> <br /> The first time you use PCD in a given Shell, you must give it the path to a directory. When entered with this path argument, PCD has the same effect as CD, changing to the named directory, but it also stores the path to the directory from which you changed. You can then change the current directory by the usual methods. To return to the initial directory, enter PCD alone. For example:<br /> <br /> 1.System:&gt; PCD Work:Paint/24bit<br /> 1.Work:Paint/24bit&gt; PCD<br /> 1.System:&gt;<br /> <br /> Subsequent invocations of PCD switch to the directory in which you last used PCD:<br /> <br /> 1.System:&gt; PCD<br /> 1.Work:Paint/24bit&gt; /<br /> 1.Work:Paint&gt; PCD<br /> 1.System:&gt;<br /> <br /> PCD use the assign list to store the remembered directory. When you use PCD, the list contains the assignment from&lt;n&gt; , where &lt;n&gt; is the Shell number. Using PCD with no argument before establishing the first from directory produces an error requester.<br /> <br /> For further examples of PCD, see Chapter 8.<br /> <br /> = L: Directory =<br /> <br /> This directory contains device handlers, which are software modules that go between AmigaDOS and the devices used by the Amiga. However, most handlers are treated as if they are actual physical devices and they are referred to by their device name.<br /> <br /> Handlers must be named in the mount file or MountList for their respective devices. Handlers are called and manipulated by programs, not users. New handlers can be supplied with some devices or programs and should be copied to the L: directory.<br /> <br /> == Aux-Handler ==<br /> <br /> The Aux-handler provides unbuffered serial input and output. It is essentially a console handler that uses the serial port rather than the Amiga screen and keyboard.<br /> <br /> The DOSDrivers mount file for AUX is:<br /> <br /> Handler = L:Aux-handler<br /> Stacksize = 1000<br /> Priority = 5<br /> <br /> You can use Aux-Handler to use a serial terminal with your Amiga. For example:<br /> <br /> 1&gt; NEWSHELL AUX: <br /> <br /> == Queue-Handler (PIPE:) ==<br /> <br /> The Queue-Handler is an input/output mechanism used to provide I/O communication between programs. It creates an interprocess communication channel named PIPE. For more information about PIPE:, see Appendix D.<br /> <br /> == Port-Handler ==<br /> <br /> The Port-Handler is the AmigaDOS interface for the SER:, PAR:, and PRT: devices.<br /> <br /> When accessing SER:, you can supply settings for the baud rate and control information. The form for this is SER:&lt;baud/control&gt;, where baud is a number representing the baud rate and where control is a three character sequence indicating the following:<br /> <br /> {| class=&quot;wikitable&quot;<br /> | Number of read/write bits || First character; either 7 or 8<br /> |-<br /> | Parity || Second character; N (no parity), O (odd parity), E (even parity), M (mark parity), S (space parity)<br /> |-<br /> | Number of stops bits || Third character; either 1 or 2<br /> |}<br /> <br /> For example:<br /> <br /> SER:9600/8N1<br /> <br /> connects to the serial port, sets the baud rate to 9600 with a bit data, no parity, and one stop bit.<br /> <br /> If you specify no baud rate or control values when accessing SER:, the values set in the Serial Preferences editor are used.<br /> <br /> == CrossDOSFileSystem ==<br /> <br /> The CrossDOSFileSystem is required to use CrossDOS.<br /> <br /> == FileSystem_Trans ==<br /> <br /> The FileSystem_Trans directory contains the following files required for CrossDOS text translation:<br /> <br /> {| class=&quot;wikitable&quot;<br /> | DANSK.crossdos || Filters Danish text files<br /> |-<br /> | INTL.crossdos || Preserves international characters<br /> |-<br /> | MAC.crossdos || Converts Apple Macintosh ASCII files<br /> |}<br /> <br /> == CDFileSystem ==<br /> <br /> The CDFileSystem is required to use a CD-ROM drive.<br /> <br /> = FONTS: =<br /> <br /> FONTS: is the disk or directory that contains the information for all of the different styles of fonts available to the Amiga. Font information is stored differently for bitmap and outline fonts.<br /> <br /> == Bitmap Fonts ==<br /> <br /> For each bitmap font, there is a subdirectory and a .font file. The font subdirectory contains files for the different point sizes that are available. Each of these files contains the bitmap representation of every character in the font at that point size.<br /> <br /> For example, for the Emerald font, there is an Emerald directory and an Emerald.font file. The Emerald directory contains two files: 17 and 20. The files contain the data needed for the 17 point Emerald font and the 20 point Emerald font, respectively. The Emerald.font file contains the list of point sizes and any available styles, such as bold and italics for the font.<br /> <br /> Many word processor or desktop publishing programs contain additional fonts that you should copy to your FONTS: directory. After you add new fonts to FONTS:, run the FixFonts program to create the .font file for the new additions.<br /> <br /> The Topaz font is the default font used by the Amiga. In addition to existing in FONTS:, Topaz 8 and Topaz 9 are built into ROM so that text can always be displayed; however only Topaz 11 is in the Topaz directory.<br /> <br /> == Outline Fonts ==<br /> <br /> The Compugraphic Intellifont outline font system used on the Amiga stores font data differently. As with the bitmap fonts, there is a .font file for each typeface. There is also a .otag file for each. The two subdirectories _bullet and _bullet_outlines contain the actual outline information for the typefaces installed on your system. You should not try to manipulate these files directly. Always use the Intellifont program or your applications' font installation tools to manage outline fonts.<br /> <br /> = LIBS: Directory =<br /> <br /> LIBS: contains libraries of software routines and math functions commonly used by the operating system and applications. The files found in the LIBS: directory are:<br /> <br /> {| class=&quot;wikitable&quot;<br /> ! .library File !! Function<br /> |-<br /> | amigaguide.library || Functions used by the AmigaGuide hypertext system.<br /> |-<br /> | asl.library || File, font, and screen mode requester functions.<br /> |-<br /> | Bullet.library || Library functions for finding and loading outline fonts.<br /> |-<br /> | Commodities.library || Functions used by Commodities Exchange programs.<br /> |-<br /> | datatypes.library || Functions for enabling manipulation ot the file types in DEVS:DataTypes.<br /> |-<br /> | Diskfont.library || Library functions for finding and loading font files.<br /> |-<br /> | iffparse.library || Functions to read IFF files.<br /> |-<br /> | locale.library || Functions for using localization features in the Amiga operating system.<br /> |-<br /> | lowlevel.library || Library to aid in game programming.<br /> |-<br /> | mathieeedoubbas.library || Double-precision IEEE math routine functions for basic functions (addition, subtraction, and so forth).<br /> |-<br /> | mathieeedoubtrans.library || Double-precision IEEE math routine functions for transcendental functions (sine, cosine, and so forth).<br /> |-<br /> | mathieeesingtrans.library || Fast single-precision IEEE math routine functions.<br /> |-<br /> | Mathtrans.library || FFP transcendental function math routine functions.<br /> |-<br /> | Realtime.library || Function to synchronize multimedia events, such as music and animation.<br /> |-<br /> | Rexxsupport.library || Functions used by ARexx.<br /> |-<br /> | Rexxsyslib.library || Main ARexx functions.<br /> |-<br /> | Version.library || Contains current software version and revision information.<br /> |-<br /> | 68040.library || Functions needed on Amigas using the 68040 microprocessor chip.<br /> |}<br /> <br /> = REXX: =<br /> <br /> REXX: is another name normally assigned to the SYS:S directory in addition to S:. Storing any ARexx programs you write in REXX: allows you to execute them without entering the full path. Create a new directory and reASSIGN REXX: to it if you wish to keep ARexx programs separate from AmigaDOS scripts.<br /> <br /> = LOCALE: =<br /> <br /> LOCALE: is where the Amiga looks for language and country files when it needs to display non-English text. On floppy systems, LOCALE: is the Locale floppy. On hard disk systems, it is the SYS:Locale directory.<br /> <br /> LOCALE: contains four directories:<br /> <br /> {| class=&quot;wikitable&quot;<br /> | Countries || Contains a .country file for all available countries. These files hold country-specific information, such as date/time format and monetary symbols.<br /> |-<br /> | Languages || Contains .language files for the available languages. These files hold general language-specific information, such as the days of the week.<br /> |-<br /> | Catalogs || Contains subdirectories for the available languages, each of which contains a Sys directory. This directory holds translated text for that language. Catalogs/&lt;language&gt;/Sys holds menu, gadget, and message text for that language.<br /> |-<br /> | Help (HELP:) || Contains subdirectories for the available languages, each of which contains a Sys directory. This directory holds translated text for that language. Help/&lt;language&gt;/Sys is reserved for AmigaGuide text files for any applications that have AmigaGuide help in that language.<br /> |}<br /> <br /> = ENVARC: =<br /> <br /> ENVARC: is the name assigned to the directory SYS:Prefs/Env-Archive. ENVARC: always contains a Sys directory, in which each of the Preferences editors stores the .prefs file created when you save a setting with its Save gadget. Custom default icons created in IconEdit are also saved here. (Named settings saved with the Save As menu item in an Editor are stored by default in the Prefs/Presets drawer.)<br /> <br /> Other Workbench programs that allow you to save configuration settings, such as MultiView, also place their files in ENVARC:<br /> <br /> = ENV: =<br /> <br /> ENV: is the directory RAM:Env, into which the contents of ENVARC: are copied when booting. Preferences settings activated with Save or Use gadgets are stored in ENV:. Global environment variables are also stored here, as small files.<br /> <br /> = CLIPS: =<br /> <br /> The directory RAM:Clipboards has the assigned name CLIPS:. It stores information clipped with the Cut or Copy items on a program's Edit menu.<br /> <br /> = T: =<br /> <br /> T: is the RAM:T directory, which may be used by scripts and some commands for storing miscellaneous temporary files.<br /> <br /> = Classes =<br /> <br /> The Classes directory stores information related to the object-oriented features of the Workbench, such as the DataTypes system upon which MultiView is based. Classes contains the directories DataTypes and Gadgets.<br /> <br /> = C: =<br /> <br /> C: is the SYS:C directory, which stores non-internal AmigaDOS commands. It is always in the search path.</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=AmigaOS_Manual:_Workbench_Before_You_Start&diff=7236 AmigaOS Manual: Workbench Before You Start 2014-02-15T18:56:32Z <p>Bill Borsari: /* Monitor Compatibility */</p> <hr /> <div>Before you start using your Amiga, there are a few things you should know and must do. If you have never used an Amiga before, there are terms and instructions in this chapter with which you may not be familiar. This information is provided here to get you started without having to know everything about your system. Although you may never have used an Amiga before, by following the instructions you can make language and keyboard selections and, if necessary, install your software. We recommend that you read all instructions before beginning any operations. We also recommend that you read through this manual to familiarize yourself with Workbench, its components, and how to use it.<br /> <br /> This chapter provides you with information about:<br /> <br /> * Using a compatible monitor<br /> * Choosing a language<br /> * Choosing a keyboard<br /> * Installing the complete Workbench software<br /> * Installing languages<br /> * Getting started <br /> <br /> = Monitor Compatibility for AmigaOS4 =<br /> <br /> Your monitor allows you to interact with your Amiga. The Next Generation Amiga offers high speed PCI and PCIe interfaces and support for many Radeon based Video cards. Each video card offers different capabilities and ports to connect to the Monitor. <br /> <br /> With the variety of possible connections and monitor capabilities and industry standard has been developed to allow systems and monitors to communicate and establish supported resolutions and color capabilities. This technology is known as Display Data Channel or DCC. More information on that standard can be found here: http://en.wikipedia.org/wiki/Display_Data_Channel.<br /> <br /> With support for DDC the vast majority modern of monitors become automatically supported by the system on system bootup with no interaction by you. You can review the available monitor settings by opening the ScreenMode preferences located in sys:/Prefs. <br /> <br /> Quicktip: You can press &quot;Right-Amiga-E&quot; and type &quot;screenmode&quot; in to the execute command window to launch the preference program.<br /> <br /> <br /> == Monitor Compatibility For Amiga OS 3.9 and earlier ==<br /> Your monitor allows you to interact with your Amiga. Many different monitors are compatible with the Amiga, which offers a variety of display options to suit your monitor's capabilities. Through the ScreenMode Preferences editor provided by the Workbench software, you can choose how your monitor's display appears.<br /> <br /> Not all monitors are compatible with your Amiga when it is powered on (booted) for the first time. All Amigas, except those quipped with a hardware display enhancer, require that the monitor used for the first boot be able to display 15 kHz scan modes. If you are using a multiscan monitor or other monitor that can display 15 kHz modes, you should have no problem seeing and using your display after the initial boot. If you are not sure if your monitor syncs to 16 kHz, consult the documentation that came with it or contact your dealer.<br /> <br /> If you do not have the hardware display enhancer and your monitor is VGA-only or does not sync to 15 kHz, your display will be distorted until an appropriate ScreenMode Preferences editor setting is made. Since you cannot reach this editor the first time you power on your Amiga using a VGA-only monitor, we recommend that you make and save your initial settings using a monitor that displays 15 kHz modes. We also recommend that you make at least one backup floppy disk copy of your Workbench software containing these initial ScreenMode editor settings in case you ever need to recover your display. If you have a problem doing this, consult your dealer or request that your dealer makes your initial settings for you.<br /> <br /> You should be able to use your VGA-only monitor with the Advanced Graphics Architecture (AGA) chip set; however, there may be limitations on the screen display modes that you can use. Most games do not work with VGA-only monitors. See Chapter 7 for more information on scan rates and screen display modes.<br /> <br /> = Choosing a Language =<br /> <br /> If you wish to interact with the Workbench in any language other than English, you must select your preferred language after you initially boot the system or following successful software installation. We recommend that you load all of the languages that you may want to use during the installation. However, if your language is not available, you can install it at a later time. For instructions on selecting a language for Amiga Workbench processing, see Chapter 6 in this manual.<br /> <br /> If you have a floppy-only system, to use a language other than English, you must follow the procedures for copying information and setting preferences described in Appendix B.<br /> <br /> = Choosing a Keyboard =<br /> <br /> If you wish to use a keyboard other than the default American, you must choose a keyboard type in the Input Preferences editor to activate it. For your keyboard to be available in the Input editor's keyboard list, its corresponding keymap must be present in the Devs/Keymaps drawer. If you are not sure which keyboard/keymap combination you have, consult your dealer.<br /> <br /> {{Note|If you are reinstalling your system software, be sure to select your keymap since the installation process overwrites the existing keymap file, deleting the old contents.}}<br /> <br /> If your keymap is not in DEVS:Keymaps, you can load it during software installation or you can drag its icon from the Storage/Keymaps drawer on your disk set to the Devs/Keymaps drawer as described with the Input Preferences editor in Chapter 5. The Input editor description includes a list of keyboards and their corresponding keymaps. (Floppy-only system users follow the same procedures described in Chapter 5.)<br /> <br /> {{Note|If you are working in a language other than English and you are using a keyboard other than USA, you must use dead keys to procedure accented characters. See the KeyShow description in Chapter 10 for information about using dead keys.}}<br /> <br /> = Software Installation =<br /> <br /> Workbench software comes preinstalled on most Amiga hard drive models. In this case, you do not need to install system software unless:<br /> <br /> * You are upgrading your software from a previous release level.<br /> * You reformat your hard disk. <br /> <br /> If you are not certain your system is preloaded, consult your dealer.<br /> <br /> Once your software is installed, if your system does not have all the languages that you want to use, the Installer lets you load any of them at a later time without running a full installation.<br /> <br /> == Installing System Software ==<br /> <br /> The following procedures describe how to install the system software on your hard drive:<br /> <br /> # Insert the Amiga Install disk into any floppy disk drive.<br /> # Boot your system (turn it off and on again).<br /> # Moving your mouse on a flat surface, place the tip of the pointer on the screen onto the icon (picture) labeled Install and quickly press (click) the left mouse button twice. A window containing drawer icons is displayed on the screen.<br /> # Using your mouse, move the tip of the pointer onto the icon for the Install drawer and quickly press the left mouse button twice. A window containing icons representing the various languages is displayed on the screen.<br /> # Using your mouse, move the tip of the pointer onto the icon for the language that you want to use during the installation and quickly press the left mouse button twice. This selects a language for the installation process only.&lt;br/&gt;If you choose any language other than English and LOCALE: is not available, a message asking you to insert the disk containing the Locale drawer is displayed. Remove the Install disk from the floppy disk drive and insert the disk containing the Locale drawer. A message prompts you to reinsert the Install disk after Locale has been read. Clicking on the Help button displays help in your chosen language.<br /> # The next screen allows you to continue the installation or abort. Click on Proceed to continue.<br /> # Choose between installing the complete software or updating languages only on the next screen. If you are installing the software, click on the Install Release button. If you only need to install a language, click on the Update Languages button and follow the instructions.<br /> # Select an installation mode on the next screen. Click the left mouse button once on the button to the left of your choice. Then click the left mouse button once on the Proceed With Install button.<br /> # The next three screens ask you which languages, printer drivers, and keymaps you wish to install. On every screen click once in the box next to each of the languages, printer drivers, and keymaps you intend to use. Click on the Proceed button when you are done with each screen.&lt;br/&gt;If you are not sure which keymap is appropriate for your particular keyboard, consult your dealer. Printer drivers are described in detail in Chapter 9.<br /> # The Installer starts loading the software from the disks. Follow the instructions on the screen, inserting disks as requested.<br /> # When the installation is compete, remove the Install floppy and reboot your system. Select Proceed to reboot or you can reboot manually.<br /> # To use Workbench in any language other than English, you must select your preferred language in the Locale Preferences Editor. See Chapter 6 for instructions and information on choosing a language.<br /> # To use any keymap/keyboard other than the default American keymap/keyboard, you must select a keyboard in the Input Preferences editor to activate the corresponding keymap in DEVS:. See Chapter 5 for instructions on activating your keyboard and a list of keyboards and corresponding keymaps.</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=AmigaOS_Manual:_Workbench_Before_You_Start&diff=7235 AmigaOS Manual: Workbench Before You Start 2014-02-15T18:55:57Z <p>Bill Borsari: /* Monitor Compatibility */</p> <hr /> <div>Before you start using your Amiga, there are a few things you should know and must do. If you have never used an Amiga before, there are terms and instructions in this chapter with which you may not be familiar. This information is provided here to get you started without having to know everything about your system. Although you may never have used an Amiga before, by following the instructions you can make language and keyboard selections and, if necessary, install your software. We recommend that you read all instructions before beginning any operations. We also recommend that you read through this manual to familiarize yourself with Workbench, its components, and how to use it.<br /> <br /> This chapter provides you with information about:<br /> <br /> * Using a compatible monitor<br /> * Choosing a language<br /> * Choosing a keyboard<br /> * Installing the complete Workbench software<br /> * Installing languages<br /> * Getting started <br /> <br /> = Monitor Compatibility =<br /> <br /> Your monitor allows you to interact with your Amiga. The Next Generation Amiga offers high speed PCI and PCIe interfaces and support for many Radeon based Video cards. Each video card offers different capabilities and ports to connect to the Monitor. <br /> <br /> With the variety of possible connections and monitor capabilities and industry standard has been developed to allow systems and monitors to communicate and establish supported resolutions and color capabilities. This technology is known as Display Data Channel or DCC. More information on that standard can be found here: http://en.wikipedia.org/wiki/Display_Data_Channel.<br /> <br /> With support for DDC the vast majority modern of monitors become automatically supported by the system on system bootup with no interaction by you. You can review the available monitor settings by opening the ScreenMode preferences located in sys:/Prefs. <br /> <br /> Quicktip: You can press &quot;Right-Amiga-E&quot; and type &quot;screenmode&quot; in to the execute command window to launch the preference program.<br /> <br /> <br /> == Monitor Compatibility For Amiga OS 3.9 and early ==<br /> Your monitor allows you to interact with your Amiga. Many different monitors are compatible with the Amiga, which offers a variety of display options to suit your monitor's capabilities. Through the ScreenMode Preferences editor provided by the Workbench software, you can choose how your monitor's display appears.<br /> <br /> Not all monitors are compatible with your Amiga when it is powered on (booted) for the first time. All Amigas, except those quipped with a hardware display enhancer, require that the monitor used for the first boot be able to display 15 kHz scan modes. If you are using a multiscan monitor or other monitor that can display 15 kHz modes, you should have no problem seeing and using your display after the initial boot. If you are not sure if your monitor syncs to 16 kHz, consult the documentation that came with it or contact your dealer.<br /> <br /> If you do not have the hardware display enhancer and your monitor is VGA-only or does not sync to 15 kHz, your display will be distorted until an appropriate ScreenMode Preferences editor setting is made. Since you cannot reach this editor the first time you power on your Amiga using a VGA-only monitor, we recommend that you make and save your initial settings using a monitor that displays 15 kHz modes. We also recommend that you make at least one backup floppy disk copy of your Workbench software containing these initial ScreenMode editor settings in case you ever need to recover your display. If you have a problem doing this, consult your dealer or request that your dealer makes your initial settings for you.<br /> <br /> You should be able to use your VGA-only monitor with the Advanced Graphics Architecture (AGA) chip set; however, there may be limitations on the screen display modes that you can use. Most games do not work with VGA-only monitors. See Chapter 7 for more information on scan rates and screen display modes.<br /> <br /> = Choosing a Language =<br /> <br /> If you wish to interact with the Workbench in any language other than English, you must select your preferred language after you initially boot the system or following successful software installation. We recommend that you load all of the languages that you may want to use during the installation. However, if your language is not available, you can install it at a later time. For instructions on selecting a language for Amiga Workbench processing, see Chapter 6 in this manual.<br /> <br /> If you have a floppy-only system, to use a language other than English, you must follow the procedures for copying information and setting preferences described in Appendix B.<br /> <br /> = Choosing a Keyboard =<br /> <br /> If you wish to use a keyboard other than the default American, you must choose a keyboard type in the Input Preferences editor to activate it. For your keyboard to be available in the Input editor's keyboard list, its corresponding keymap must be present in the Devs/Keymaps drawer. If you are not sure which keyboard/keymap combination you have, consult your dealer.<br /> <br /> {{Note|If you are reinstalling your system software, be sure to select your keymap since the installation process overwrites the existing keymap file, deleting the old contents.}}<br /> <br /> If your keymap is not in DEVS:Keymaps, you can load it during software installation or you can drag its icon from the Storage/Keymaps drawer on your disk set to the Devs/Keymaps drawer as described with the Input Preferences editor in Chapter 5. The Input editor description includes a list of keyboards and their corresponding keymaps. (Floppy-only system users follow the same procedures described in Chapter 5.)<br /> <br /> {{Note|If you are working in a language other than English and you are using a keyboard other than USA, you must use dead keys to procedure accented characters. See the KeyShow description in Chapter 10 for information about using dead keys.}}<br /> <br /> = Software Installation =<br /> <br /> Workbench software comes preinstalled on most Amiga hard drive models. In this case, you do not need to install system software unless:<br /> <br /> * You are upgrading your software from a previous release level.<br /> * You reformat your hard disk. <br /> <br /> If you are not certain your system is preloaded, consult your dealer.<br /> <br /> Once your software is installed, if your system does not have all the languages that you want to use, the Installer lets you load any of them at a later time without running a full installation.<br /> <br /> == Installing System Software ==<br /> <br /> The following procedures describe how to install the system software on your hard drive:<br /> <br /> # Insert the Amiga Install disk into any floppy disk drive.<br /> # Boot your system (turn it off and on again).<br /> # Moving your mouse on a flat surface, place the tip of the pointer on the screen onto the icon (picture) labeled Install and quickly press (click) the left mouse button twice. A window containing drawer icons is displayed on the screen.<br /> # Using your mouse, move the tip of the pointer onto the icon for the Install drawer and quickly press the left mouse button twice. A window containing icons representing the various languages is displayed on the screen.<br /> # Using your mouse, move the tip of the pointer onto the icon for the language that you want to use during the installation and quickly press the left mouse button twice. This selects a language for the installation process only.&lt;br/&gt;If you choose any language other than English and LOCALE: is not available, a message asking you to insert the disk containing the Locale drawer is displayed. Remove the Install disk from the floppy disk drive and insert the disk containing the Locale drawer. A message prompts you to reinsert the Install disk after Locale has been read. Clicking on the Help button displays help in your chosen language.<br /> # The next screen allows you to continue the installation or abort. Click on Proceed to continue.<br /> # Choose between installing the complete software or updating languages only on the next screen. If you are installing the software, click on the Install Release button. If you only need to install a language, click on the Update Languages button and follow the instructions.<br /> # Select an installation mode on the next screen. Click the left mouse button once on the button to the left of your choice. Then click the left mouse button once on the Proceed With Install button.<br /> # The next three screens ask you which languages, printer drivers, and keymaps you wish to install. On every screen click once in the box next to each of the languages, printer drivers, and keymaps you intend to use. Click on the Proceed button when you are done with each screen.&lt;br/&gt;If you are not sure which keymap is appropriate for your particular keyboard, consult your dealer. Printer drivers are described in detail in Chapter 9.<br /> # The Installer starts loading the software from the disks. Follow the instructions on the screen, inserting disks as requested.<br /> # When the installation is compete, remove the Install floppy and reboot your system. Select Proceed to reboot or you can reboot manually.<br /> # To use Workbench in any language other than English, you must select your preferred language in the Locale Preferences Editor. See Chapter 6 for instructions and information on choosing a language.<br /> # To use any keymap/keyboard other than the default American keymap/keyboard, you must select a keyboard in the Input Preferences editor to activate the corresponding keymap in DEVS:. See Chapter 5 for instructions on activating your keyboard and a list of keyboards and corresponding keymaps.</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=AmigaOS_Manual:_AmigaDOS_Selecting_an_Interface&diff=7012 AmigaOS Manual: AmigaDOS Selecting an Interface 2014-01-31T06:21:32Z <p>Bill Borsari: </p> <hr /> <div>Although the Amiga comes with the Workbench graphical user interface (GUI) and most AmigaDOS operations can be run from the Workbench without opening a Shell window, there are several reasons to also learn how to use the AmigaDOS command line interface. Among the advantages of working directly with AmigaDOS are:<br /> <br /> * Personal preference<br /> : Some users prefer working with text and keyboard rather than a mouse and icons. This may be a matter of personal taste or due to familiarity with some other text-based computer system.<br /> <br /> * Workbench limitations<br /> : Although most basic operations can be accomplished with equal ease through the Shell or the Workbench, there are functions that can be done only with AmigaDOS commands. These include certain basic system configuration tasks and the running of scripts and utilities that do not have icons. Note that all AmigaDOS functions are available in Workbench using the Execute Command item in the Workbench menu.<br /> <br /> * Speed<br /> : Users who can type reasonably well and are familiar with AmigaDOS commands often find that typing a command is faster than performing the equivalent operation with the mouse. This is particularly true when more than one command must be executed. Shell-based capabilities, such as pattern matching and redirection, make some tasks particularly easy when compared to Workbench methods. In addition, the text output of AmigaDOS commands usually displays faster than do requesters and windows full if icons.<br /> <br /> * Control and flexibility<br /> : Running programs from the Shell makes it easier to control Amiga Multitasking. Also, when using applications, such as software compilers that offer numerous run-time options, it is Quicker to specify often-changed options a command line than by editing the Tool Types of an icon.<br /> <br /> * Scripting<br /> : Performing complex, repetitive, and/or unattended tasks is difficult, if not impossible, using a GUI. Such tasks are ideally suited to scripts, which are text files of AmigaDOS commands.<br /> <br /> * Saving resources for your applications<br /> : The text interface requires less memory, disk space, and other system resources than the graphic imagery of a GUI.<br /> <br /> = Choosing Your Interface =<br /> <br /> Although some users prefer to use the Shell or the Workbench exclusively, most can make use of both once they learn the basics of AmigaDOS. Because Shell windows open on the Workbench screen, it is easy to switch back and forth between the two methods of working. Whether you do something through the Workbench or the Shell depends on the method that appears easiest to you for that particular task.<br /> <br /> == Workbench Users ==<br /> <br /> Although you can work primarily in Workbench, we recommend that you become familiar with AmigaDOS because you may need to use AmigaDOS commands or examine a script to determine ist function. The many convenience features of the Amiga Shell make the process of learning and using AmigaDOS considerably easier than most command line systems. If you prefer not to use AmigaDOS directly, you can attach scripts and Shell-only commands to icons.<br /> <br /> == Shell Users ==<br /> <br /> For Shell users who choose not to open the Workbench, the Amiga's built-in GUI support is still an asset. Shell windows - like Workbench windows - can be quickly moved, sized, depth-adjusted, and opened or closed at will using the mouse. Shell windows can be opened on public screens other than the Workbench. FKey, MouseBlanker, and other Commodity utilities allow you to further customize your command line working environment.</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=AmigaOS_Manual:_AmigaDOS&diff=7011 AmigaOS Manual: AmigaDOS 2014-01-31T06:20:27Z <p>Bill Borsari: /* Operating System Features */</p> <hr /> <div>{{WIP}}<br /> = Welcome =<br /> <br /> The Amiga line of personal computers offers a unique combination of versatility, computing power, and usability. The fast, multitasking Amiga operating system allows users at any level of experience to take advantage of their system's resources.<br /> <br /> AmigaDOS its the Amiga Disk Operating System. A disk operating system is software that manages data manipulation and control on the computer, such as:<br /> <br /> * Providing a filing system that organizes the data that programs use and produce<br /> * Handling information storage and retrieval from floppy disks, hard, disks, and other storage media<br /> <br /> Providing an interface to peripheral devices, such as printers and modems<br /> <br /> AmigaDOS provides a Command Line Interface (CLI), which means that you work with it through typed commands. Some of these commands parallel familiar Workbench operations, such as Copy, Rename, and Format Disk. There are also advanced commands that allow you to create scripts for performing repetitive tasks, to monitor the use of memory, and to perform other tasks unavailable through the Workbench. The commands are entered through a special window, known as a Shell window. Shell windows open on the Workbench screen and are similar to other Workbench windows, except that Shell windows only display text.<br /> <br /> Together AmigaDOS and the Amiga Shell offer you a powerful and flexible operating environment with these features.<br /> <br /> = Operating System Features =<br /> <br /> * Complete control over all aspects of Amiga operation<br /> * Hierarchical file system<br /> * Filenames up to 256 characters, upper/lower case preserved without case-sensitivity<br /> * Configurable command search path<br /> * Pattern matching<br /> * Background command processing<br /> * Many commands internal, others can be made memory resident<br /> * Shared libraries<br /> * Multiple file systems supported, including CrossDOS (MS-DOS file system)<br /> <br /> = Shell Features =<br /> <br /> * Multiple, independent Shell windows<br /> * Shell windows sizable, draggable, depth-adjustable<br /> * Configurable prompt, font, and text color and style<br /> * Command history and command line editing<br /> * Fast character-mapped display<br /> * Aliases<br /> * Local and global environment variables<br /> * Scripting<br /> * Command input and output redirection<br /> * Multiple directory assignment<br /> * Copy and paste text among console windows<br /> * ARexx support<br /> <br /> = Using this Manual =<br /> <br /> This manual, which should be used in conjunction with the Workbench User's Guide, describes the AmigaDOS software, its components, and how to use it. It assumes that you are familiar with Workbench, but have never worked with AmigaDOS. If this is the case, we recommend that you read through the entire manual to learn the concepts associated with the Amiga operating system before beginning to use it. After you have familiarized yourself with AmigaDOS, use this manual as a reference tool when executing commands or writing programs or scripts.<br /> <br /> The following is a brief description of each chapter and appendix:<br /> <br /> [[AmigaOS Manual: AmigaDOS Selecting an Interface|Chapter 1. Selecting an Interface]] This chapter gives information to help you determine when to use AmigaDOS rather than Workbench.<br /> <br /> [[AmigaOS Manual: AmigaDOS Understanding the Shell|Chapter 2. Understanding the AmigaDOS Shell]] This chapter describes the AmigaDOS Shell in detail.<br /> <br /> [[AmigaOS Manual: AmigaDOS Working With AmigaDOS|Chapter 3. Working with AmigaDOS]] This chapter describes the file management system, types of commands, and components of AmigaDOS commands.<br /> <br /> [[AmigaOS Manual: AmigaDOS Using the Editors|Chapter 4. Using the Editors]] This chapter provides a full explanation for using the ED text editor and command listings for the MEmacs and EDIT text editors.<br /> <br /> [[AmigaOS Manual: AmigaDOS Using Scripts|Chapter 5. Using Scripts]] This chapter describes AmigaDOS scripts and how to create them.<br /> <br /> [[AmigaOS Manual: AmigaDOS Command Reference|Chapter 6. AmigaDOS Command Reference]] This chapter describes each AmigaDOS command in detail.<br /> <br /> [[AmigaOS Manual: AmigaDOS Workbench-Related Command Reference|Chapter 7. Workbench-Related Command Reference]] This chapter describes the Workbench-related commands usable from AmigaDOS.<br /> <br /> [[AmigaOS Manual: AmigaDOS Command Examples|Chapter 8. Command Examples]] This chapter provides examples of how to perform common tasks with AmigaDOS commands.<br /> <br /> [[AmigaOS Manual: AmigaDOS Error Messages|Appendix A. Error Messages]] This chapter contains a list of possible program problems and suggested solutions.<br /> <br /> [[AmigaOS Manual: AmigaDOS Additional Amiga Directories|Appendix B. Additional Amiga Directories]] This chapter describes S:, DEVS:, L:, FONTS:, and other directories.<br /> <br /> Appendix C: Using Floppy-Only-Systems: This chapter tells you how to make the most of your system if you only have one floppy drive and no hard drive. '''Obsolete and not available'''<br /> <br /> [[AmigaOS Manual: AmigaDOS Advanced Features|Appendix D. Advanced AmigaDOS Features]] This chapter provides information on customizing AmigaDOS for advanced Amiga users.<br /> <br /> [[AmigaOS Manual: AmigaDOS Glossary|AmigaDOS Glossary]]<br /> <br /> = Documentation Conventions =<br /> <br /> The following conventions are used in this manual:<br /> <br /> ; COMMANDS, ASSIGNS, DEVICES and NAMES<br /> : Commands, their keywords, device names, and assigned directories are displayed in all upper case letters. File and directory names are displayed in initial caps. However, they do not need to be entered this way. The Amiga ignores case differences in commands and arguments.<br /> <br /> ; &lt;n&gt;<br /> : Angle brackets enclose variable information that you must supply. In place of &lt;n&gt;, substitute the value, text, or option desired. Do not enter the angle brackets when entering the variable.<br /> <br /> ; Courier<br /> : Text appearing in the Courier font represents information that you type in or text displayed in a window in response to a command.<br /> <br /> ; Key1 + Key2<br /> : Key combinations displayed with a + (plus) sign connecting them indicate pressing the keys simultaneously. For example, Ctrl+C indicates that you hold down the Ctrl key and, while holding it down, press C.<br /> <br /> ; Key1, Key2<br /> : Key combinations displayed with a comma separating them indicate pressing the keys in sequence. For example, Esc,O indicates that you press and release the Esc key, followed by the O key.<br /> <br /> ; Return<br /> : Directions to press the Return key indicate that you press the large odd shaped key on the right side of the keyboard above the right shift key.<br /> <br /> ; Enter<br /> : Directions to &quot;enter&quot; something indicate that you type in the indicated information and press Return.<br /> <br /> ; command line indentation<br /> : On command lines that are long enough to wrap to the next line, this manual shows the wrapped lines as indented for documentation purposes only. In practice, the wrapped lines align with the first character of the Shell prompt.<br /> <br /> = Related Documentation =<br /> <br /> AmigaDOS Quick Reference<br /> <br /> Workbench User's Guide<br /> <br /> [[AmigaOS_Manual:_ARexx|ARexx User's Guide]]<br /> <br /> In addition, the [[DeveloperDoc:Main|AmigaOS Developer Documentation]] provide technical documentation of AmigaDOS for programmers and developers.</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=Tutorials:Main&diff=6561 Tutorials:Main 2013-09-24T23:29:03Z <p>Bill Borsari: /* AmiWest 2012 */</p> <hr /> <div>= Tutorials =<br /> <br /> Tutorials have been provided by various authors.<br /> <br /> == General ==<br /> <br /> [[The Hacking Way: Part 1 - First Steps]]<br /> <br /> [[The Right Tool for the Job (Shared Objects)]]<br /> <br /> [[How to Build Stubs for 68k Libraries]]<br /> <br /> == Debugging ==<br /> <br /> [[How to install a hardware interrupt]]<br /> <br /> [[How to open and use the exec debug interface]]<br /> <br /> [[GDB for Beginners]]<br /> <br /> [[Using Crash-Logs for Debugging]]<br /> <br /> [[Debug Logging on AmigaOS]]<br /> <br /> [[Redirecting Debug Output to the Serial Port on Startup]]<br /> <br /> [[Advanced Serial Debugging Guide]]<br /> <br /> == GUI ==<br /> <br /> [[BOOPSI Gadget Help Strings]]<br /> <br /> [[BOOPSI Popup Menus - Part 1]]<br /> <br /> [[BOOPSI Popup Menus - Part 2]]<br /> <br /> == AmiWest 2013 ==<br /> <br /> [[AmiWest 2013 Programming Conference Synopsis]]<br /> <br /> {{Note|This section is under development and will be changing.}}<br /> <br /> == AmiWest 2012 ==<br /> <br /> [[AmiWest Setup]] [https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Introduction-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 1|AmiWest Lesson 1: Coding Basics]] [https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson01-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 2|AmiWest Lesson 2: AmigaOS Fundamentals]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson02-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 3|AmiWest Lesson 3: Input and Output]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson03-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 4|AmiWest Lesson 4: ProcTree]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson04-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 5|AmiWest Lesson 5: MIDI]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson05-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 6|AmiWest Lesson 6: Application Library - Not Presented]]<br /> <br /> [[AmiWest Lesson 7|AmiWest Lesson 7: Screen Blanker]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson07-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 8|AmiWest Lesson 8: ARexx Ports]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson08-360.mp4 - Video]<br /> <br /> [[AmiWest Support]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Wrap-Up-360.mp4 - Video]</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=Tutorials:Main&diff=6560 Tutorials:Main 2013-09-24T23:28:35Z <p>Bill Borsari: /* AmiWest 2012 */</p> <hr /> <div>= Tutorials =<br /> <br /> Tutorials have been provided by various authors.<br /> <br /> == General ==<br /> <br /> [[The Hacking Way: Part 1 - First Steps]]<br /> <br /> [[The Right Tool for the Job (Shared Objects)]]<br /> <br /> [[How to Build Stubs for 68k Libraries]]<br /> <br /> == Debugging ==<br /> <br /> [[How to install a hardware interrupt]]<br /> <br /> [[How to open and use the exec debug interface]]<br /> <br /> [[GDB for Beginners]]<br /> <br /> [[Using Crash-Logs for Debugging]]<br /> <br /> [[Debug Logging on AmigaOS]]<br /> <br /> [[Redirecting Debug Output to the Serial Port on Startup]]<br /> <br /> [[Advanced Serial Debugging Guide]]<br /> <br /> == GUI ==<br /> <br /> [[BOOPSI Gadget Help Strings]]<br /> <br /> [[BOOPSI Popup Menus - Part 1]]<br /> <br /> [[BOOPSI Popup Menus - Part 2]]<br /> <br /> == AmiWest 2013 ==<br /> <br /> [[AmiWest 2013 Programming Conference Synopsis]]<br /> <br /> {{Note|This section is under development and will be changing.}}<br /> <br /> == AmiWest 2012 ==<br /> <br /> [[AmiWest Setup]] [https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Introduction-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 1|AmiWest Lesson 1: Coding Basics]] [https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson01-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 2|AmiWest Lesson 2: AmigaOS Fundamentals]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson02-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 3|AmiWest Lesson 3: Input and Output]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson03-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 4|AmiWest Lesson 4: ProcTree]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson04-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 5|AmiWest Lesson 5: MIDI]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson05-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 6|AmiWest Lesson 6: Application Library]]<br /> <br /> [[AmiWest Lesson 7|AmiWest Lesson 7: Screen Blanker]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson07-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 8|AmiWest Lesson 8: ARexx Ports]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson08-360.mp4 - Video]<br /> <br /> [[AmiWest Support]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Wrap-Up-360.mp4 - Video]</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=AmiWest_Lesson_7&diff=6557 AmiWest Lesson 7 2013-09-18T16:40:58Z <p>Bill Borsari: Created page with &quot;This tutorial is in video form only.&quot;</p> <hr /> <div>This tutorial is in video form only.</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=Tutorials:Main&diff=6556 Tutorials:Main 2013-09-18T16:40:18Z <p>Bill Borsari: /* AmiWest 2012 */</p> <hr /> <div>= Tutorials =<br /> <br /> Tutorials have been provided by various authors.<br /> <br /> == General ==<br /> <br /> [[The Hacking Way: Part 1 - First Steps]]<br /> <br /> [[The Right Tool for the Job (Shared Objects)]]<br /> <br /> [[How to Build Stubs for 68k Libraries]]<br /> <br /> == Debugging ==<br /> <br /> [[How to install a hardware interrupt]]<br /> <br /> [[How to open and use the exec debug interface]]<br /> <br /> [[GDB for Beginners]]<br /> <br /> [[Using Crash-Logs for Debugging]]<br /> <br /> [[Debug Logging on AmigaOS]]<br /> <br /> [[Redirecting Debug Output to the Serial Port on Startup]]<br /> <br /> [[Advanced Serial Debugging Guide]]<br /> <br /> == GUI ==<br /> <br /> [[BOOPSI Gadget Help Strings]]<br /> <br /> [[BOOPSI Popup Menus - Part 1]]<br /> <br /> [[BOOPSI Popup Menus - Part 2]]<br /> <br /> == AmiWest 2013 ==<br /> <br /> [[AmiWest 2013 Programming Conference Synopsis]]<br /> <br /> {{Note|This section is under development and will be changing.}}<br /> <br /> == AmiWest 2012 ==<br /> <br /> [[AmiWest Setup]] [https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Part01-Introduction-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 1|AmiWest Lesson 1: Coding Basics]] [https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Part02-Lesson01-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 2|AmiWest Lesson 2: AmigaOS Fundamentals]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Part03-Lesson02-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 3|AmiWest Lesson 3: Input and Output]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Part04-Lesson03-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 4|AmiWest Lesson 4: ProcTree]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Part06-Lesson04-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 5|AmiWest Lesson 5: MIDI]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Part07-Lesson05-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 6|AmiWest Lesson 6: Application Library]]<br /> <br /> [[AmiWest Lesson 7|AmiWest Lesson 7: Screen Blanker]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Part05-Lesson07-360.mp4 - Video]<br /> <br /> [[AmiWest Lesson 8|AmiWest Lesson 8: ARexx Ports]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Part08-Lesson08-360.mp4 - Video]<br /> <br /> [[AmiWest Support]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Part09-Wrap-Up-360.mp4 - Video]</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=Tutorials:Main&diff=6390 Tutorials:Main 2013-09-02T18:20:43Z <p>Bill Borsari: /* AmiWest 2012 */</p> <hr /> <div>= Tutorials =<br /> <br /> Tutorials have been provided by various authors.<br /> <br /> == General ==<br /> <br /> [[The Hacking Way: Part 1 - First Steps]]<br /> <br /> [[The Right Tool for the Job (Shared Objects)]]<br /> <br /> [[How to Build Stubs for 68k Libraries]]<br /> <br /> == Debugging ==<br /> <br /> [[How to install a hardware interrupt]]<br /> <br /> [[How to open and use the exec debug interface]]<br /> <br /> [[GDB for Beginners]]<br /> <br /> [[Using Crash-Logs for Debugging]]<br /> <br /> [[Debug Logging on AmigaOS]]<br /> <br /> [[Redirecting Debug Output to the Serial Port on Startup]]<br /> <br /> [[Advanced Serial Debugging Guide]]<br /> <br /> == GUI ==<br /> <br /> [[BOOPSI Gadget Help Strings]]<br /> <br /> [[BOOPSI Popup Menus - Part 1]]<br /> <br /> [[BOOPSI Popup Menus - Part 2]]<br /> <br /> == AmiWest 2013 ==<br /> <br /> [[AmiWest 2013 Programming Conference Synopsis]]<br /> <br /> {{Note|This section is under development and will be changing.}}<br /> <br /> == AmiWest 2012 ==<br /> <br /> [[AmiWest Setup]]<br /> <br /> [[AmiWest Lesson 1|AmiWest Lesson 1: Coding Basics]]<br /> <br /> [[AmiWest Lesson 2|AmiWest Lesson 2: AmigaOS Fundamentals]]<br /> <br /> [[AmiWest Lesson 3|AmiWest Lesson 3: Input and Output]]<br /> <br /> [[AmiWest Lesson 4|AmiWest Lesson 4: ProcTree]]<br /> <br /> [[AmiWest Lesson 5|AmiWest Lesson 5: MIDI]]<br /> <br /> [[AmiWest Lesson 7|AmiWest Lesson 6: Screen Blanker]]<br /> <br /> [[AmiWest Lesson 8|AmiWest Lesson 7: ARexx Ports]]<br /> <br /> [[AmiWest Support]]</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=Exec_Lists_and_Queues&diff=4894 Exec Lists and Queues 2013-03-10T21:10:56Z <p>Bill Borsari: /* Exec List Example */</p> <hr /> <div>== Exec Lists and Queues ==<br /> <br /> The Amiga system software operates in a dynamic environment of data structures. An early design goal of Exec was to keep the system flexible and open-ended by eliminating artificial boundaries on the number of system structures used. Rather than using static system tables, Exec uses dynamically created structures that are added and removed as needed. These structures can be put in an unordered ''list'', or in an ordered ''list'' known as a ''queue''. A list can be empty, but never full. This concept is central to the design of Exec. Understanding lists and queues is important to understanding not only Exec itself, but also the mechanism behind the Amiga's message and port based inter-process communication.<br /> <br /> Exec uses lists to maintain its internal database of system structures. Tasks, interrupts, libraries, devices, messages, I/O requests, and all other Exec data structures are supported and serviced through the consistent application of Exec's list mechanism. Lists have a common data structure, and a common set of functions is used for manipulating them. Because all of these structures are treated in a similar manner, only a small number of list handling functions need be supported by Exec.<br /> <br /> == List Structure ==<br /> <br /> A list is composed of a ''header'' and a doubly-linked chain of elements called ''nodes''. The header contains memory pointers to the first and last nodes of the linked chain. The address of the header is used as the handle to the entire list. To manipulate a list, you must provide the address of its header.<br /> <br /> [[File:LibFig23-1.png|center]]<br /> <br /> &lt;center&gt;'''Figure 23-1: Simplified Overview of an Exec List'''&lt;/center&gt;<br /> <br /> Nodes may be scattered anywhere in memory. Each node contains two pointers; a successor and a predecessor. As illustrated above, a list header contains two placeholder nodes that contain no data. In an empty list, the head and tail nodes point to each other.<br /> <br /> === Node Structure Definition ===<br /> <br /> A Node structure is divided into three parts: linkage, information, and content. The linkage part contains memory pointers to the node's successor and predecessor nodes. The information part contains the node type, the priority, and a name pointer. The content part stores the actual data structure of interest. For nodes that require linkage only, a small MinNode structure is used.<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct MinNode<br /> {<br /> struct MinNode *mln_Succ;<br /> struct MinNode *mln_Pred;<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ; mln_Succ<br /> : points to the next node in the list (successor).<br /> <br /> ; mln_Pred<br /> : points to the previous node in the list (predecessor).<br /> <br /> When a type, priority, or name is required, a full-featured Node structure is used.<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct Node<br /> {<br /> struct Node *ln_Succ;<br /> struct Node *ln_Pred;<br /> UBYTE ln_Type;<br /> BYTE ln_Pri;<br /> char *ln_Name;<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ; ln_Type<br /> : defines the type of the node (see &amp;lt;exec/nodes.h&amp;gt; for a list).<br /> <br /> ; ln_Pri<br /> : specifies the priority of the node (+127 (highest) to -128 (lowest)).<br /> <br /> ; ln_Name<br /> : points to a printable name for the node (a NULL-terminated string).<br /> <br /> The Node and MinNode structures are often incorporated into larger structures, so groups of the larger structures can easily be linked together. For example, the Exec Interrupt structure is defined as follows:<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct Interrupt<br /> {<br /> struct Node is_Node;<br /> APTR is_Data;<br /> VOID (*is_Code)();<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Here the is_Data and is_Code fields represent the useful content of the node. Because the Interrupt structure begins with a Node structure, it may be passed to any of the Exec List manipulation functions.<br /> <br /> === Node Initialization ===<br /> <br /> Before linking a node into a list, certain fields may need initialization. Initialization consists of setting the ln_Type, ln_Pri, and ln_Name fields to their appropriate values (A MinNode structure does not have these fields). The successor and predecessor fields do not require initialization.<br /> <br /> The ln_Type field contains the data type of the node. This indicates to Exec (and other subsystems) the type, and hence the structure, of the content portion of the node (the extra data after the Node structure). The standard system types are defined in the &amp;lt;exec/nodes.h&amp;gt; include file. Some examples of standard system types are NT_TASK, NT_INTERRUPT, NT_DEVICE, and NT_MSGPORT.<br /> <br /> The ln_Pri field uses a signed numerical value ranging from +127 to -128 to indicate the priority of the node. Higher-priority nodes have greater values; for example, 127 is the highest priority, zero is nominal priority, and -128 is the lowest priority. Some Exec lists are kept sorted by priority order. In such lists, the highest-priority node is at the head of the list, and the lowest-priority node is at the tail of the list. Most Exec node types do not use a priority. In such cases, initialize the priority field to zero.<br /> <br /> The ln_Name field is a pointer to a NULL-terminated string of characters. Node names are used to find and identify list-bound objects (like public message ports and libraries), and to bind symbolic names to actual nodes. Names are also useful for debugging purposes, so it is a good idea to provide every node with a name. Take care to provide a valid name pointer; Exec does not copy name strings.<br /> <br /> This fragment initializes a Node called myInt, an instance of the Interrupt data structure introduced above.<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct Interrupt interrupt;<br /> <br /> interrupt.is_Node.ln_Type = NT_INTERRUPT;<br /> interrupt.is_Node.ln_Pri = -10;<br /> interrupt.is_Node.ln_Name = &quot;sample.interrupt&quot;;<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === List Header Structure Definition ===<br /> <br /> As mentioned earlier, a list header maintains memory pointers to the first and last nodes of the linked chain of nodes. It also serves as a handle for referencing the entire list. The minimum list header (&quot;mlh_&quot;) and the full-featured list header (&quot;lh_&quot;) are generally interchangeable.<br /> <br /> The structure MinList defines a minimum list header.<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct MinList<br /> {<br /> struct MinNode *mlh_Head;<br /> struct MinNode *mlh_Tail;<br /> struct MinNode *mlh_TailPred;<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ; mlh_Head<br /> : points to the first node in the list.<br /> <br /> ; mlh_Tail<br /> : is always NULL.<br /> <br /> ; mlh_TailPred<br /> : points to the last node in the list.<br /> <br /> In a few limited cases a full-featured List structure will be required:<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct List<br /> {<br /> struct Node *lh_Head;<br /> struct Node *lh_Tail;<br /> struct Node *lh_TailPred;<br /> UBYTE lh_Type;<br /> UBYTE lh_Pad;<br /> };<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ; lh_Type<br /> : defines the type of nodes within the list (see &amp;lt;exec/nodes.h&amp;gt;).<br /> <br /> ; lh_Pad<br /> : is a structure alignment byte.<br /> <br /> One subtlety here must be explained further. The list header is constructed in an efficient, but confusing manner. Think of the header as a structure containing the head and tail nodes for the list. The head and tail nodes are placeholders, and never carry data. The head and tail portions of the header actually overlap in memory. lh_Head and lh_Tail form the head node; lh_Tail and lh_TailPred form the tail node. This makes it easy to find the start or end of the list, and eliminates any special cases for insertion or removal.<br /> <br /> [[File:LibFig23-2.png|center]]<br /> <br /> &lt;center&gt;'''Figure 23-2: List Header Overlap'''&lt;/center&gt;<br /> <br /> The lh_Head and lh_Tail fields of the list header act like the ln_Succ and lh_Pred fields of a node. The lh_Tail field is set permanently to NULL, indicating that the head node is indeed the first on the list - that is, it has no predecessors. See the figure below.<br /> <br /> Likewise, the lh_Tail and lh_TailPred fields of the list header act like the ln_Succ and lh_Pred fields of a node. Here the NULL lh_Tail indicates that the tail node is indeed the last on the list-that is, it has no successors. See the figure below.<br /> <br /> === Header Initialization ===<br /> <br /> List headers must be properly initialized before use. It is not adequate to initialize the entire header to zero. The head and tail entries must have specific values. The header must be initialized as follows:<br /> <br /> # Set the lh_Head field to the address of lh_Tail.<br /> # Clear the lh_Tail field.<br /> # Set the lh_TailPred field to the address of lh_Head.<br /> # Set lh_Type to the same data type as the nodes to be kept the list. (Unless you are using a MinList).<br /> <br /> [[File:LibFig23-3.png|center]]<br /> <br /> &lt;center&gt;'''Figure 23-3: Initializing a List Header Structure'''&lt;/center&gt;<br /> <br /> The functions NewList() and NewMinList() are provided to properly initialize a List or MinList respectively prior to use.<br /> <br /> == List Functions ==<br /> <br /> Exec provides a number of symmetric functions for handling lists. There are functions for inserting and removing nodes, for adding and removing head and tail nodes, for inserting nodes in a priority order, and for searching for nodes by name. The prototypes for Exec list handling functions are as follows.<br /> <br /> {|<br /> | VOID AddHead( struct List *list, struct Node *node );<br /> |-<br /> | VOID AddTail( struct List *list, struct Node *node );<br /> |-<br /> | VOID Enqueue( struct List *list, struct Node *node );<br /> |-<br /> | struct Node *FindIName( struct List *list, STRPTR name );<br /> |-<br /> | struct Node *FindName( struct List *list, STRPTR name );<br /> |-<br /> | struct Node *GetHead(struct List *list);<br /> |-<br /> | struct Node *GetPred(struct Node *node);<br /> |-<br /> | struct Node *GetSucc(struct Node *node);<br /> |-<br /> | struct Node *GetTail(struct List *list);<br /> |-<br /> | VOID Insert( struct List *list, struct Node *node, struct Node *pred );<br /> |-<br /> | VOID Remove( struct Node *node );&lt;br /&gt;<br /> |-<br /> | struct Node *RemHead( struct List *list );&lt;br /&gt;<br /> |-<br /> | struct Node *RemTail( struct List *list );&lt;br /&gt;<br /> |-<br /> | VOID NewList( struct List *list );&lt;br /&gt;<br /> |-<br /> | VOID NewMinList( struct MinList *list );<br /> |}<br /> <br /> In this discussion of the Exec list handling functions, header represents a pointer to List header, and node represents pointer to a Node.<br /> <br /> === Insertion and Removal ===<br /> <br /> The Insert() function is used for inserting a new node into any position in a list. It always inserts the node following a specified node that is already part of the list. For example, Insert(header,node,pred) inserts the node node after the node pred in the specified list. If the pred node points to the list header or is NULL, the new node will be inserted at the head of the list. Similarly, if the pred node points to the lh_Tail of the list, the new node will be inserted at the tail of the list. However, both of these actions can be better accomplished with the functions mentioned in the &quot;Special Case Insertion&quot; section below.<br /> <br /> The Remove() function is used to remove a specified node from a list. For example, Remove(node) will remove the specified node from whatever list it is in. ''To be removed, a node must actually be in a list.'' If you attempt to remove a node that is not in a list, you will cause serious system problems.<br /> <br /> === Special Case Insertion ===<br /> <br /> Although the Insert() function allows new nodes to be inserted at the head and the tail of a list, the AddHead() and AddTail() functions will do so with higher efficiency. Adding to the head or tail of a list is common practice in first-in-first-out (FIFO) or last-in-first-out (LIFO or stack) operations. For example, AddHead(header,node) would insert the node at the head of the specified list.<br /> <br /> === Special Case Removal ===<br /> <br /> The two functions RemHead() and RemTail() are used in combination with AddHead() and AddTail() to create special list ordering. When you combine AddTail() and RemHead(), you produce a first-in-first-out (FIFO) list. When you combine AddHead() and RemHead() a last-in-first-out (LIFO or stack) list is produced. RemTail() exists for symmetry. Other combinations of these functions can also be used productively.<br /> <br /> Both RemHead() and RemTail() remove a node from the list, and return a pointer to the removed node. If the list is empty, the function return a NULL result.<br /> <br /> === MinList / MinNode Operations ===<br /> <br /> All of the above functions and macros will work with long or short format node structures. A MinNode structure contains only linkage information. A full Node structure contains linkage information, as well as type, priority and name fields. The smaller MinNode is used where space and memory alignment issues are important. The larger Node is used for queues or lists that require a name tag for each node.<br /> <br /> === Prioritized Insertion ===<br /> <br /> The list functions discussed so far do not make use of the priority field in a Node. The Enqueue() function is equivalent to Insert(), except it inserts nodes into a list sorting them according to their priority. It keeps the higher-priority nodes towards the head of the list. All nodes passed to this function must have their priority and name assigned prior to the call. Enqueue(header,mynode) inserts mynode behind the lowest priority node with a priority greater than or equal to mynode's. For Enqueue() to work properly, the list must already be sort according to priority. Because the highest priority node is at the head of the list, the RemHead() function will remove the highest-priority node. Likewise, RemTail() will remove the lowest-priority node.<br /> <br /> {{Note|title=FIFO Is Used For The Same Priority|text=If you add a node that has the same priority as another node in the queue, Enqueue() will use FIFO ordering. The new node is inserted following the last node of equal priority.}}<br /> <br /> === Searching by Name ===<br /> <br /> Because many lists contain nodes with symbolic names attached (via the ln_Name field), it is possible to find a node by its name. This naming technique is used throughout Exec for such nodes as tasks, libraries, devices, and resources.<br /> <br /> The FindName() function searches a list for the first node with a given name. For example, FindName(header, &amp;quot;Furrbol&amp;quot;) returns a pointer to the first node named &quot;Furrbol.&quot; If no such node exists, a NULL is returned.<br /> <br /> The case of the name characters is significant; &quot;foo&quot; is different from &quot;Foo.&quot; If the case of a name should not be significant then use the FindIName() function.<br /> <br /> [[File:LibFig23-4.png|center]]<br /> <br /> &lt;center&gt;'''Figure 23-4: Complete Sample List Showing all Interconnections'''&lt;/center&gt;<br /> <br /> === More on the Use of Named Lists ===<br /> <br /> To find multiple occurrences of nodes with identical names, the FindName() or FindIName() function is called multiple times. For example, if you want to find all the nodes with the name pointed to by name:<br /> <br /> &lt;syntaxhighlight&gt;<br /> VOID DisplayName(struct List *list, CONST_STRPTR name)<br /> {<br /> struct Node *node;<br /> <br /> if (node = IExec-&gt;FindName(list, name))<br /> while (node)<br /> {<br /> IDOS-&gt;Printf(&quot;Found %s at location %lx\n&quot;, node-&gt;ln_Name, node);<br /> node = IExec-&gt;FindName((struct List *)node, name);<br /> }<br /> else IDOS-&gt;Printf(&quot;No node with name %s found.\n&quot;, name);<br /> }<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Notice that the second search uses the node found by the first search. The FindName() function ''never'' compares the specified name with that of the starting node. It always begins the search with the successor of the starting point.<br /> <br /> === Empty Lists ===<br /> <br /> It is often important to determine if a list is empty. This can be done in many ways, but only two are worth mentioning. If either the lh_TailPred field is pointing to the list header or the ln_Succ field of the lh_Head is NULL, then the list is empty.<br /> <br /> These methods would be written as follows:<br /> <br /> &lt;syntaxhighlight&gt;<br /> /* You can use this method... */<br /> if (list-&gt;lh_TailPred == (struct Node *)list)<br /> IDOS-&gt;Printf(&quot;list is empty\n&quot;);<br /> <br /> /* Or you can use this method */<br /> if (NULL == list-&gt;lh_Head-&gt;ln_Succ)<br /> IDOS-&gt;Printf(&quot;list is empty\n&quot;);<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Macros are available to make code easier to read:<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct List *list;<br /> struct MinList *minlist;<br /> <br /> if (IsListEmpty(list))<br /> IDOS-&gt;Printf(&quot;list is empty\n&quot;);<br /> <br /> if (IsMinListEmpty(minlist))<br /> IDOS-&gt;Printf(&quot;minlist is empty\n&quot;);<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === Scanning a List ===<br /> <br /> Occasionally a program may need to scan a list to locate a particular node, find a node that has a field with a particular value, or just print the list. Because lists are linked in both the forward and backward directions, the list can be scanned from either the head or tail.<br /> <br /> There are two methods to traverse lists in AmigaOS. One way is via direct manipulation of the pointers. The other way uses functions from Exec.<br /> <br /> Here is a code fragment that uses pointers and ''for'' loop to print the names of all nodes in a list:<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct List *list;<br /> struct Node *node;<br /> <br /> for (node = list-&gt;lh_Head ; node-&gt;ln_Succ ; node = node-&gt;ln_Succ)<br /> IDOS-&gt;Printf(&quot;%p -&gt; %s\n&quot;, node, node-&gt;ln_Name);<br /> &lt;/syntaxhighlight&gt;<br /> <br /> A common mistake is to process the head or tail nodes. Valid data nodes have non-NULL successor and predecessor pointers. The above loop exits when node-&gt;ln_Succ is NULL.<br /> <br /> Another common mistake is to free a node from within a loop, then reference the free memory to obtain the next node pointer. An extra temporary pointer solves this second problem. Here is an example:<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct List *list;<br /> struct Node *node, *next;<br /> <br /> for (node = list-&gt;lh_Head; node-&gt;ln_Succ; node = next)<br /> {<br /> next = node-&gt;ln_Succ;<br /> /* Do something with node. */<br /> /* This may include node removal from list. */<br /> if( some_condition )<br /> {<br /> IExec-&gt;Remove(node);<br /> }<br /> }<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Here is a code fragment that uses functions and ''for'' loop to print the names of all nodes in a list:<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct List *list;<br /> struct Node *node;<br /> <br /> for (node = IExec-&gt;GetHead() ; node != NULL ; node = IExec-&gt;GetSucc(node))<br /> IDOS-&gt;Printf(&quot;%p -&gt; %s\n&quot;, node, node-&gt;ln_Name);<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Here is an example showing how to properly remove a node from a list while traversing:<br /> <br /> &lt;syntaxhighlight&gt;<br /> struct List *list;<br /> struct Node *node, *next;<br /> <br /> for (node = IExec-&gt;GetHead(list); node != NULL; node = next)<br /> {<br /> next = IExec-&gt;GetSucc(node);<br /> /* Do something with node. */<br /> /* This may include node removal from list. */<br /> if( some_condition )<br /> {<br /> IExec-&gt;Remove(node);<br /> }<br /> }<br /> &lt;/syntaxhighlight&gt;<br /> <br /> Programmers are free to choose the method they prefer. Performance is not likely a concern unless the code is used in a critical section of a program.<br /> <br /> ==== Exec List Example ====<br /> <br /> The code below demonstrates the concepts and functions discussed in this section by building an application-defined Exec List.<br /> <br /> &lt;syntaxhighlight&gt;<br /> // buildlist.c - example which uses an application-specific Exec list<br /> <br /> #include &lt;exec/types.h&gt;<br /> #include &lt;exec/lists.h&gt;<br /> #include &lt;exec/nodes.h&gt;<br /> #include &lt;exec/memory.h&gt;<br /> <br /> #include &lt;proto/exec.h&gt;<br /> #include &lt;proto/dos.h&gt;<br /> #include &lt;proto/utility.h&gt;<br /> <br /> /* Our function prototypes */<br /> VOID AddName(struct List *, CONST_STRPTR);<br /> VOID FreeNameNodes(struct List *);<br /> VOID DisplayNameList(struct List *);<br /> VOID DisplayName(struct List *, CONST_STRPTR);<br /> <br /> struct NameNode {<br /> struct Node nn_Node; /* System Node structure */<br /> TEXT nn_Data[62]; /* Node-specific data */<br /> };<br /> <br /> #define NAMENODE_ID 100 /* The type of &quot;NameNode&quot; */<br /> <br /> int main()<br /> {<br /> struct List *NameList; /* Note that a MinList would also work */<br /> <br /> NameList = IExec-&gt;AllocSysObjectTags(ASOT_LIST, TAG_END);<br /> <br /> if (NameList == NULL)<br /> IDOS-&gt;Printf(&quot;Out of memory\n&quot;);<br /> else {<br /> AddName(NameList,&quot;Name7&quot;); AddName(NameList,&quot;Name6&quot;);<br /> AddName(NameList,&quot;Name5&quot;); AddName(NameList,&quot;Name4&quot;);<br /> AddName(NameList,&quot;Name2&quot;); AddName(NameList,&quot;Name0&quot;);<br /> <br /> AddName(NameList,&quot;Name7&quot;); AddName(NameList,&quot;Name5&quot;);<br /> AddName(NameList,&quot;Name3&quot;); AddName(NameList,&quot;Name1&quot;);<br /> <br /> DisplayName(NameList,&quot;Name5&quot;);<br /> DisplayNameList(NameList);<br /> <br /> FreeNameNodes(NameList);<br /> IExec-&gt;FreeSysObject(ASOT_LIST, NameList); /* Free list header */<br /> }<br /> <br /> return 0;<br /> }<br /> <br /> /* Allocate a NameNode structure, copy the given name into the structure,<br /> * then add it the specified list. This example does not provide an<br /> * error return for the out of memory condition.<br /> */<br /> VOID AddName(struct List *list, CONST_STRPTR name)<br /> {<br /> struct NameNode *namenode = IExec-&gt;AllocSysObjectTags(ASOT_NODE,<br /> ASONODE_Size, sizeof(struct NameNode),<br /> ASONODE_Type, NAMENODE_ID,<br /> TAG_END);<br /> <br /> if (namenode == NULL)<br /> IDOS-&gt;Printf(&quot;Out of memory\n&quot;);<br /> else {<br /> IUtility-&gt;Strlcpy(namenode-&gt;nn_Data, name, sizeof(namenode-&gt;nn_Data));<br /> namenode-&gt;nn_Node.ln_Name = namenode-&gt;nn_Data;<br /> IExec-&gt;AddHead((struct List *)list, (struct Node *)namenode);<br /> }<br /> }<br /> <br /> /*<br /> * Free the entire list, including the header. The header is not updated<br /> * as the list is freed. This function demonstrates how to avoid<br /> * referencing freed memory when deallocating nodes.<br /> */<br /> VOID FreeNameNodes(struct List *list)<br /> {<br /> struct NameNode *worknode;<br /> struct NameNode *nextnode;<br /> <br /> worknode = (struct NameNode *)(IExec-&gt;GetHead(list)); /* First node */<br /> while ((nextnode = (struct NameNode *)(IExec-&gt;GetSucc((struct *Node)worknode)))) {<br /> IExec-&gt;FreeSysObject(ASOT_NODE, worknode);<br /> worknode = nextnode;<br /> }<br /> }<br /> <br /> /*<br /> * Print the names of each node in a list.<br /> */<br /> VOID DisplayNameList(struct List *list)<br /> {<br /> struct Node *node;<br /> <br /> if (IsListEmpty(list))<br /> IDOS-&gt;Printf(&quot;List is empty.\n&quot;);<br /> else {<br /> for (node = IExec-&gt;GetHead(list); node != NULL; node = IExec-&gt;GetSucc(node))<br /> IDOS-&gt;Printf(&quot;%lx -&gt; %s\n&quot;, node, node-&gt;ln_Name);<br /> }<br /> }<br /> <br /> /*<br /> * Print the location of all nodes with a specified name.<br /> */<br /> VOID DisplayName(struct List *list, CONST_STRPTR name)<br /> {<br /> struct Node *node;<br /> <br /> if ((node = IExec-&gt;FindName(list, name))) {<br /> while (node) {<br /> IDOS-&gt;Printf(&quot;Found a %s at location %lx\n&quot;, node-&gt;ln_Name, node);<br /> node = IExec-&gt;FindName((struct List *)node,name);<br /> }<br /> } else IDOS-&gt;Printf(&quot;No node with name %s found.\n&quot;, name);<br /> }<br /> &lt;/syntaxhighlight&gt;<br /> <br /> === Important Note About Shared Lists ===<br /> <br /> It is possible to run into contention problems with other tasks when manipulating a list that is shared by more than one task. ''None'' of the standard Exec list functions arbitrates for access to the list. For example, if some other task happens to be modifying a list while your task scans it, an inconsistent view of the list may be formed. This can result in a corrupted system.<br /> <br /> Generally it is not permissible to read or write a shared list without first locking out access from other tasks. ''All'' users of a list must use the same arbitration method. Several arbitration techniques are used on the Amiga. Some lists are protected by a semaphore. The ObtainSemaphore() call grants ownership of the list (see the [[Exec_Semaphores|Exec Semaphores]] for more information). Some lists require special arbitration. For example, you must use the Intuition LockIBase(0) call before accessing any Intuition lists. Other lists may be accessed only during Forbid() or Disable() (see [[Exec_Tasks|Exec Tasks]] for more information).<br /> <br /> The preferred method for arbitrating use of a shared list is through semaphores because a semaphores only holds off other tasks that are trying to access the shared list. Rather than suspending all multitasking. Failure to lock a shared list before use ''will'' result in unreliable operation.<br /> <br /> Note that I/O functions including printf() generally call Wait() to wait for I/O completion, and this allows other tasks to run. Therefore, it is not safe to print or Wait() while traversing a list unless the list is fully controlled by your application, or if the list is otherwise guaranteed not to change during multitasking.<br /> <br /> == Function Reference ==<br /> <br /> The following charts give a brief description of the Exec list and queue functions and macros. See the SDK for details about each call.<br /> <br /> {| class=&quot;wikitable&quot;<br /> ! Exec Function<br /> ! Description<br /> |-<br /> | AddHead()<br /> | Insert a node at the head of a list.<br /> |-<br /> | AddTail()<br /> | Append a node to the tail of a list.<br /> |-<br /> | Enqueue()<br /> | Insert or append a node to a system queue.<br /> |-<br /> | FindIName()<br /> | Find a node with a given name in a system list ignoring case.<br /> |-<br /> | FindName()<br /> | Find a node with a given name in a system list.<br /> |-<br /> | GetHead()<br /> | Gets the head node of a list.<br /> |-<br /> | GetPred()<br /> | Gets the node predecessor.<br /> |-<br /> | GetSucc()<br /> | Gets the node successor.<br /> |-<br /> | GetTail()<br /> | Gets the tail node of a list.<br /> |-<br /> | Insert()<br /> | Insert a node into a list.<br /> |-<br /> | IsMinListEmpty<br /> | Test if minimal list is empty<br /> |-<br /> | IsListEmpty<br /> | Test if list is empty<br /> |-<br /> | NewMinList()<br /> | Initialize a minimal list structure for use.<br /> |-<br /> | NewList()<br /> | Initialize a list structure for use.<br /> |-<br /> | MoveList()<br /> | Moves all the nodes from one list to another efficiently.<br /> |-<br /> | RemHead()<br /> | Remove the head node from a list.<br /> |-<br /> | Remove()<br /> | Remove a node from a list.<br /> |-<br /> | RemTail()<br /> | Remove the tail node from a list.<br /> |}</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=Configuring_Workbench_and_AmigaOS&diff=2191 Configuring Workbench and AmigaOS 2012-05-11T04:52:14Z <p>Bill Borsari: </p> <hr /> <div>[[amigaos41ahi|AHI]] (Audio Hardware Interface) - Allows for control over the audio functions of your Amiga<br /> <br /> [[amigaos41amigainput|AmigaInput]] - Setup for gamepads and joysticks<br /> <br /> [[amigaos41asl|ASL]] - Allows for control over file requesters<br /> <br /> [[amigaos41compatibility|Compatibility]] - Manages the 68K Just-in-time compiler settings<br /> <br /> [[amigaos41console|Console]] - Controls the settings for the Amiga Shell<br /> <br /> [[amigaos41deficons|DefIcons]] - Interface to allow behavor of default icon<br /> <br /> [[amigaos41dos|DOS]] - Manages DOS settings<br /> <br /> [[amigaos41font|Font]] - Controls Font selection for Workbench, Screens, and Windows<br /> <br /> [[amigaos41gui|GUI]] - <br /> <br /> [[amigaos41input|Input]] -<br /> <br /> [[amigaos41internet|Internet]] -<br /> <br /> [[amigaos41locale|Local]] - <br /> <br /> [[amigaos41notifications|Notifications]] -<br /> <br /> [[amigaos41palette|Palette]] - <br /> <br /> [[amigaos41Picasso96Mode|Picasso96Mode]] - <br /> <br /> [[amigaos41pointer|Pointer]] - <br /> <br /> [[amigaos41popupmenu|PopupMenu]] -<br /> <br /> [[amigaos41printer|Printer]] -<br /> <br /> [[amigaos41printergfx|PrinterGfx]] -<br /> <br /> [[amigaos41printerps|PrinterPS]] -<br /> <br /> [[amigaos41screenblanker|ScreenBlanker]] -<br /> <br /> [[amigaos41screenmode|ScreenMode]] -<br /> <br /> [[amigaos41screens|Screens]] -<br /> <br /> [[amigaos41serial|Serial]] -<br /> <br /> [[amigaos41time|Time]] -<br /> <br /> [[amigaos41timezone|Timezone]] -<br /> <br /> [[amigaos41uboot|UBoot]] -<br /> <br /> [[amigaos41usb|USB]] -<br /> <br /> [[amigaos41wbpattern|WBPattern]] -<br /> <br /> [[amigaos41wbstartup|WBStartup]] -<br /> <br /> [[amigaos41workbench|Workbench]] -</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=Configuring_Workbench_and_AmigaOS&diff=2190 Configuring Workbench and AmigaOS 2012-05-11T04:51:49Z <p>Bill Borsari: </p> <hr /> <div>[[amigaos41ahi|AHI]] (Audio Hardware Interface) - Allows for control over the audio functions of your Amiga<br /> <br /> [[amigaos41amigainput|AmigaInput]] - Setup for gamepads and joysticks<br /> <br /> [[amigaos41asl|ASL]] - Allows for control over file requesters<br /> <br /> [[amigaos41compatibility|Compatibility]] - Manages the 68K Just-in-time compiler settings<br /> <br /> [[amigaos41console|Console]] - Controls the settings for the Amiga Shell<br /> <br /> [[amigaos41deficons|DefIcons]] - Interface to allow behavor of default icon<br /> <br /> [[amigaos41dos|DOS]] - Manages DOS settings<br /> <br /> [[amigaos41font|Font]] - Controls Font selection for Workbench, Screens, and Windows<br /> <br /> [[amigaos41gui|GUI]] - <br /> <br /> [[amigaos41input|Input]] -<br /> <br /> [[amigaos41internet|Internet] -<br /> <br /> [[amigaos41locale|Local]] - <br /> <br /> [[amigaos41notifications|Notifications]] -<br /> <br /> [[amigaos41palette|Palette]] - <br /> <br /> [[amigaos41Picasso96Mode|Picasso96Mode]] - <br /> <br /> [[amigaos41pointer|Pointer]] - <br /> <br /> [[amigaos41popupmenu|PopupMenu]] -<br /> <br /> [[amigaos41printer|Printer]] -<br /> <br /> [[amigaos41printergfx|PrinterGfx]] -<br /> <br /> [[amigaos41printerps|PrinterPS]] -<br /> <br /> [[amigaos41screenblanker|ScreenBlanker]] -<br /> <br /> [[amigaos41screenmode|ScreenMode]] -<br /> <br /> [[amigaos41screens|Screens]] -<br /> <br /> [[amigaos41serial|Serial]] -<br /> <br /> [[amigaos41time|Time]] -<br /> <br /> [[amigaos41timezone|Timezone]] -<br /> <br /> [[amigaos41uboot|UBoot]] -<br /> <br /> [[amigaos41usb|USB]] -<br /> <br /> [[amigaos41wbpattern|WBPattern]] -<br /> <br /> [[amigaos41wbstartup|WBStartup]] -<br /> <br /> [[amigaos41workbench|Workbench]] -</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=Configuring_Workbench_and_AmigaOS&diff=2004 Configuring Workbench and AmigaOS 2012-05-09T22:07:44Z <p>Bill Borsari: </p> <hr /> <div>[[amigaos41workbench|Workbench]]<br /> <br /> [[amigaos41internet|Internet]]<br /> <br /> [[amigaos41gui|GUI]]</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=Configuring_Workbench_and_AmigaOS&diff=2003 Configuring Workbench and AmigaOS 2012-05-09T22:07:29Z <p>Bill Borsari: Created page with &quot;Workbench Internet GUI&quot;</p> <hr /> <div>[[amigaos41workbench|Workbench]]<br /> [[amigaos41internet|Internet]]<br /> [[amigaos41gui|GUI]]</div> Bill Borsari https://wiki.amigaos.net/w/index.php?title=UserDoc:Workbench&diff=2001 UserDoc:Workbench 2012-05-09T22:06:21Z <p>Bill Borsari: </p> <hr /> <div>There is no documentation for users on this wiki yet.<br /> <br /> [[amigaos4.1prefsprograms|Amiga OS Preferences Programs]]</div> Bill Borsari