-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy path11-05-libraries-and-devices.html
497 lines (394 loc) · 24.7 KB
/
11-05-libraries-and-devices.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
<!doctype html>
<html lang="en">
<head>
<!--
This Amos Professional Manual is written by asymetrix for the Amiga community and should stay completely FREE FOREVER.
Created 2008. :)
It was created from the original AMOS Professional Manual by Europress Software Ltd.
It has been updated by Fredrik Rambris.
-->
<title>Libraries and Devices - AMOS Professional Manual</title>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, user-scalable=yes, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<meta name="keywords" content="Amos Professional, Amiga, Programming, Basic, Francois Lionet, Europress Software Ltd, Amos, computing, code, AmigaDOS">
<meta name="author" content="asymetrix,Fredrik Rambris">
<link rel="GitHub" href="https://github.com/fredrik-rambris/amospromanual">
<meta property="og:site_name" content="AMOS Professional Manual">
<meta property="og:image" content="https://amospromanual.dev/images/cover.jpg">
<link rel="stylesheet" type="text/css" href="styles.css">
<link rel="canonical" href="https://amospromanual.dev/11-05-libraries-and-devices.html">
</head>
<body>
<section>
<h1>Libraries and Devices</h1>
<p>
This Chapter deals with the exploitation of the Amiga's operating system, providing a vast range
of possibilities for the experienced system programmer. System libraries are dealt with first, and
then devices are examined.</p>
</section>
<section id="01-accessing-the-system-libraries">
<h2>Accessing the system libraries</h2>
<p>
All of the most useful calls to the Amiga's internal system libraries are already built in to AMOS
Professional. You are able to call <b>any</b> library directly from an AMOS Professional program, as
well as access all devices connected to your computer. If you really need to make contact with
these libraries and devices, the following functions are supplied. Please take note that using
them without precise knowledge is a recipe for disaster!</p>
<p>
AMOS Professional is able to execute commands from any library installed in your Amiga. These
options use the standard AMOS Professional channel system to deal with Input/Output
structures. Total access to all the standard data structures is also provided via the powerful
STRUC function, which automatically senses the type of element to be manipulated.</p>
<h3 class="command" id="i-lib-open">LIB OPEN</h3>
<p><i>instruction: open a library for use</i><br>
<b>Lib Open</b> channel number,"name.library",version</p>
<p>
The LIB OPEN command calls the OPEN LIBRARY function from EXEC. If the library is
external, it will be loaded into memory from the "Libs:" folder of your current start-up disc. If a
problem is encountered, you will be helped by the relevant error message from AMOS
Professional, and the error can easily be intercepted using a TRAP command.</p>
<p>
After the library has been initialised successfully, it remains open until the program is run again
from the Editor, or your variables are re-set using a CLEAR command, or a LIB CLOSE
command is called.</p>
<p>
Three parameters are needed for a LIB OPEN instruction. The number of a new AMOS
Professional channel, to be used to refer to this library throughout the AMOS Professional
program. Then the name of the library that is to be opened, given in standard Commodore
format. Lastly, the minimum version number of the library that is to be installed in memory
should be specified. If you are unsure of this parameter, use a value of zero.</p>
<h3 class="command" id="sysf-lib-close">LIB CLOSE</h3>
<p><i>instruction: close one or all currently open libraries</i><br>
<b>Lib Close</b><br>
<b>Lib Close</b> channel number</p>
<p>
Used on its own, the LIB CLOSE command closes all open libraries in a single operation. If an
optional Channel number is included, an individual library may be closed. Please note that if a
selected library does not exist, no error will be reported!</p>
<h3 class="command" id="sysf-lib-call">LIB CALL</h3>
<p><i>function: call a function from a library</i><br>
result=<b>Lib Call</b>(channel number,function offset)</p>
<p>
This important function acts as the gateway to <b>all</b> the functions in the selected library.
It calls the required function and returns the result to your
AMOS Professional program.</p>
<p>
The function offset parameter holds the offset value to the library function that you wish to
execute, and if it is entered directly this value must be exact. Any mistakes will crash the
computer. Alternatively, you are recommended to use a safer method via the LVO function to
call the command by name, which is explained below.</p>
<p>
Before calling this function, the appropriate parameter values need to be loaded into the
Address and Data registers, using the AREG and DREG commands. The precise format of these
parameters depends on the function in question, and should be checked from the appropriate
reference manual.</p>
<p>
After the function has been successfully executed, any return values will be available for
immediate use from the AREG and DREG variables. Note that AREG only allows the registers
from A0 to A3 to be accessed. (Registers A4, A5 and A6 are not used by the libraries at all.)</p>
<h3 class="command" id="sysf-lib-base">LIB BASE</h3>
<p><i>function: get the base address of the library</i><br>
address=<b>Lib Base</b>(channel number)</p>
<p>
LIB BASE is used to return the base address of the selected library. This can be used in
conjunction with the STRUC function to manipulate the internal data structures directly.
Obviously, the normal PEEK and POKE functions can be used for this purpose as well.</p>
<h3 class="command" id="fn-doscall">DOSCALL</h3>
<p><i>function: execute function from DOS library</i><br>
result=<b>Doscall</b>(function offset)</p>
<p>
DOSCALL executes a function directly from the DOS library, with the offset to the appropriate
function being specified in brackets. The selected command is executed straight from an AMOS
Professional program, without the need to open the DOS library in your program. This is useful
for single calls to an important routine.</p>
<p>
The offset value can either be a simple number or a named function using the LVO command.
As with LIB CALL, the control registers first need to be set up carefully. These values should be
placed into D0 to D7 and A0 to A3, with the aid of the AREG and DREG functions. After the
command has been executed, the result will be given as the return value in D0. Please note that
the contents of the other registers will <b>not</b> be loaded back into AREG and DREG.</p>
<h3 class="command" id="fn-execall">EXECALL</h3>
<p><i>function: call EXEC library</i><br>
result=<b>Execall</b>(function offset)</p>
<p>
The EXECALL function performs a call to the Amiga's EXEC library, with the specified offset
value. On entry, D0 to D7 and A0 to A2 <b>must</b> be loaded with the control settings required by the
function. A value is returned holding the contents of D0.</p>
<h3 class="command" id="fn-gfxcall">GFXCALL</h3>
<p><i>function: call Graphics library</i><br>
result=<b>Gfxcall</b>(function offset)</p>
<p>
This executes a function directly from the Graphics library, taking the parameters from the
DREG and AREG arrays. The function offset parameter enters the offset to the function you
wish to call, and can also be set using the LVO function, if required.</p>
<h3 class="command" id="fn-intcall">INTCALL</h3>
<p><i>function: call Intuition library</i><br>
result=<b>Intcall</b>(function offset)</p>
<p>
The INTCALL function calls a command directly from the Intuition library. Before using this
function, it is vital to load the appropriate control parameters into the registers D0 to D7 and A0
to A3. This can be done with the AREG and DREG variables from an AMOS Professional
program. When the function has been executed, the contents of D0 will be returned back to your
program as the result. Please note that this function is particularly dangerous, unless you are
familiar with the Intuition library.</p>
</section>
<section id="02-equates-and-offsets">
<h2>Equates and Offsets</h2>
<p>
Experienced programmers of C or Assembler languages will be used to calling most library
functions directly, by name. These names are converted invisibly into the appropriate offset
values when a program is compiled into machine code. Unfortunately, this technique only
works with compiled languages. AMOS Professional in an interpreted language, and so a
slightly different system has been adopted.</p>
<p>
An "equate" is simply a library function name converted to its internal equivalent. Instead of
supplying the usual Include files, equates have been placed in the "AMOSPro.System_Equate"
file in your "AMOSProSystem" folder. The first time a program is tested, the names are
converted into their internal equivalents by AMOS Professional. Each name is translated into a
single value, which is then saved into a permanent memory bank, ready for instant use.</p>
<p>
As you would expect from AMOS Professional, the entire process is completely automatic.
Simply define a memory bank for your equates, and use the LVO, EQU or STRUC functions
(explained below) to return the relevant offset values. Everything else is handled by AMOS
Professional.</p>
<h3 class="command" id="i-set-equate-bank">SET EQUATE BANK</h3>
<p><i>instruction: set up the automatic equate system</i><br>
<b>Set Equate Bank</b> bank number</p>
<p>
This command allocates a memory bank for use by the automatic equate system. It should be
called up <b>before</b> the first equate in your program, preferably near the beginning. Specify the
bank number to be used for your equates, ranging from 1 to 65535. Any existing bank of the
same number will be <b>erased</b> when the equates are installed in memory, without warning, so
take care!</p>
<h3 class="command" id="fn-lvo">LVO</h3>
<p><i>function: get the Library Vector Offset</i><br>
offset=<b>Lvo</b>("Name_of_the_function")</p>
<p>
This function returns the Library Vector Offset associated with a specified function. The
function name will be translated automatically when your program is tested for the first time,
and it will be placed in a memory bank for future use. Set up the memory bank with a SET
EQUATE BANK command first, otherwise an error message will be generated. If the function
name does not exist, an "Equate not found error" will be given from the Editor.</p>
<p>
The function name is in standard Commodore format, and should be typed in <b>exactly</b> as it
appears in your reference manuals. This is especially important regarding the way upper case
letters are treated differently from their lower case equivalents. For example, Input, INPUT and
input are separate keywords, only the first version will be accepted, and either of the
alternatives will generate an error when the program is tested!</p>
<p>
Also note that because the function is executed during the testing process, it <b>must</b> be a simple
string rather than an expression. For example, if you need to call the FindTask option from Exec,
you would use a line like this:</p>
<code class="prefix ex">TASK=Execall(Lvo("FindTask"))</code>
<h3 class="command" id="fn-equ">EQU</h3>
<p><i>function: get an equate</i><br>
value=<b>Equ</b>("Name_of_the_equate")</p>
<p>
The EQU function returns any standard equate value used by the Amiga system libraries. The
equate can represent anything from an offset to a structure, or even the names of various bit-
masks. Provided that it is supplied in the standard Amiga include files, it will be available from
AMOS Professional immediately. The only exceptions to this rule are the library offsets, and
these should be obtained with the LVO function.</p>
<p>
The name of the equate should be specified in brackets, and refers to the name as set out in your
reference manuals. This name is case sensitive, as explained above, so care should be taken. It is
also important to remember that the name string <b>must</b> be a constant, and that expressions are
not allowed! In fact, the technique is extremely simple. This example would send a WRITE
command to a device:</p>
<code class="prefix ex">DEV D0(channel,EQU("CMD_WRITE"))</code>
<h3 class="command" id="resv-struc">STRUC</h3>
<p><i>reserved variable: access an internal data structure</i><br>
value=<b>Struc</b>(address,"Offset Name")<br>
<b>Struc</b>(address,"Offset_Name")=value</p>
<p>
The STRUC reserved variable provides a simple way of assigning a value to any one of the
elements of a system structure, and it is intelligent!</p>
<p>
There can be problems with these structures, because the type of an element varies dramatically
from function to function. Depending on the structure, it can be anything from a single byte to a
whole string of characters. This means that before an element can be changed, the tedious
process of checking its format must be carried out.</p>
<p>
STRUC is able to identify the type of the element directly from the equates, and then handle the
entire procedure automatically, no matter if the element is a byte, a word or a longword. If the
element is a string pointer, an error will obviously be generated, but we have provided a
STRUC$ variable to cater for this!</p>
<p>
The address parameter holds the address of your structure in memory. This will usually be
returned by a LIB BASE or a DEV BASE function. The offset name is the name of the relevant
data object as listed in your manuals. The name will be converted into an offset number by
AMOS Professional, using the auto-equate system, as explained earlier. This means that a SET
EQUATE BANK command needs to be included near the beginning of your program, to
initialise this feature. For example:</p>
<code class="prefix ex">Struc(Dev Base(1),"I0_LENGTH")=TRACK_SIZE</code>
<p>The same process can be used to read a value from a structure:</p>
<code class="prefix ex">Print Struc(Dev Base(1),"I0_LENGTH")</code>
<h3 class="command" id="fn-struc-dollar">STRUC$</h3>
<p><i>function: read or write a string pointer to a structure</i><br>
value$=<b>Struc$</b>(address,"Offset_Name")<br>
<b>Struc$</b>(address,"Offset Name")="value"</p>
<p>
This is used to read or write a string of characters to the named structure in memory. If the
element is a number, an error will be generated when the program is first tested.
When used to copy a string in a buffer area, STRUC$ adds a zero to the end, and then LOKEs it.
In its alternative use, STRUC$ grabs the string from the relevant structure address, where this
address refers to the address of the structure in memory, as returned by the LIB BASE or DEV
BASE functions.</p>
<p>In both cases, the offset name refers to the name of the item to be manipulated.</p>
</section>
<section id="03-adding-equates-to-the-equates-file">
<h2>Adding equates to the equates file</h2>
<p>
If your own non-standard libraries are to be used, equate files can easily be expanded in order to
make use of your new routines.</p>
<p>
To achieve this, an assembly listing should be produced, containing the equate definitions in
standard Devpak format. This listing should then be run through the
"Equates_Generator.AMOS" program, which can be found in the root directory of the
AMOSPro_System disc.</p>
</section>
<section id="04-the-requester-extension">
<h2>The Requester Extension</h2>
<p>
As a default, the AMOS Professional requester routine will be used in preference to hit'
Workbench system requester.</p>
<h3 class="command" id="i-request-wb">REQUEST WB</h3>
<p><i>instruction: use the Workbench system requester</i><br>
<b>Request Wb</b></p>
<p>
This command is used to switch to the Workbench system requester. As soon as one of the
options is selected from it, you will be returned to AMOS Professional. Please note that if the
Requester Extension is deleted from the extension list by means of the configuration file, then
the standard Workbench requester will be used for displaying messages. This will give the
illusion that AMOS Professional has crashed when a requester appears. If this situation occurs,
simply press <kbd>Amiga</kbd> + <kbd>A</kbd> to return to the Workbench, respond to the requester and press
<kbd>Amiga</kbd> + <kbd>A</kbd> again to return to AMOS Professional. There should be no need to delete the
Requester extension unless memory is very low.</p>
<h3 class="command" id="i-request-on">REQUEST ON</h3>
<p><i>instruction: use the AMOS Professional requester routine</i><br>
<b>Request On</b></p>
<p>
This is the default setting, and is used to make AMOS Professional employ its own requester
routine.</p>
<h3 class="command" id="i-request-off">REQUEST OFF</h3>
<p><i>instruction: cancel the requester</i><br>
<b>Request Off</b></p>
<p>
If this instruction is used, AMOS Professional will automatically select the [CANCEL] button of
the requester, and the actual requester will not be displayed. This is ideal for error trapping
Within a program.</p>
</section>
<section id="05-control-of-devices">
<h2>Control of devices</h2>
<p>
AmigaDOS supports a wide range of devices for your use. Some devices are provided to control
specific items of hardware, such as printers and disc drives, while others offer access to internal
facilities like the synthetic speech handler. The following two functions need no expert
knowledge to use!</p>
<h3 class="command" id="fn-dev-first-dollar">DEV FIRST$</h3>
<p><i>function: get the first device from the current device list</i><br>
device$=<b>Dev First</b>(path$)</p>
<p>
This function is similar to DIR FIRST$. A string is returned identifying the first device that
satisfies a chosen search path in the current device list.</p>
<p>
DEV FIRST$("**") will list everything, DEV FIRST$("D/**") will only list disks, and DEV
FIRST$(A/**") is used if you only want to list assigns.</p>
<h3 class="command" id="fn-dev-next-dollar">DEV NEXT$</h3>
<p><i>function: get the next device that satisfies the current search path</i><br>
device$=<b>Dev Next$</b></p>
<p>
This is used in conjunction with the DEV FIRST$ function to get the next device in the current
device list that satisfies the specified search path. Once the last device has been found, an empty
string will be returned.</p>
<code class="prefix edit">Print Dev First$("**")
Do
A$=Dev Next$
If A$="" Then End
Print A$
Loop
</code>
<p>
AMOS Professional includes a powerful series of commands to exploit these devices directly
from your programs, but they should only be used by experienced programmers, armed with
the relevant ROM Kernel manual. You have been warned!</p>
<h3 class="command" id="i-dev-open">DEV OPEN</h3>
<p><i>instruction: open a device</i><br>
<b>Dev Open</b>(channel number,"name.device",IOlength,UnitNumber,Flags)</p>
<p>
The DEV OPEN command opens a communication port and prepares the device for use by
AMOS Professional programs. If this device is not already installed, it will be loaded from the
"DEVS" folder of your current start-up disc automatically. Floppy disc users may be requested to
swap discs at this point.</p>
<p>
The selected device will now remain active during the course of the program, and will only be
closed if a DEV CLOSE command is called, or a RUN command is used to clear the variable area,
or a CLEAR operation is undertaken.</p>
<p>
The specified channel number should be from zero to 4, the "name.device" parameter enters the
name of the device to be initialised in normal AmigaDOS format, and IOlength specified the
length of the IO structure to be created for the device. If in doubt, use a value of 256, which
should be sufficient for most devices. The final flags parameter sets the status of the device flags
if applicable. Please refer to your system documentation for details.</p>
<p>DEV OPEN performs the following operations:</p>
<ul>
<li>Firstly, a communication port is created and initialised.</li>
<li>Next, an IO Ext structure is opened, ready for communication.</li>
<li>Lastly, the OPEN DEVICE function is executed with the new structure.</li>
</ul>
<h3 class="command" id="i-dev-close">DEV CLOSE</h3>
<p><i>instruction: close one or more devices</i><br>
<b>Dev Close</b><br>
<b>Dev Close</b> channel</p>
<p>Use this command to close one or more open devices.</p>
<p>
Memory used by the IO structure will be returned back to AMOS Professional and the message
port is released for subsequent use. If the channel number is omitted, all active devices are
closed simultaneously, otherwise the single specified device is closed down. Note that if a
specified channel is not already open, no error will be reported.</p>
<h3 class="command" id="i-dev-do">DEV DO</h3>
<p><i>instruction: call a command using DoI0</i><br>
<b>Dev Do</b> channel number,command number</p>
<p>
The DEV DO instruction executes a DoIO operation via the specified channel. Obviously the
correct internal structure parameters must be set using a STRUC command, before this
operation is called. The specified channel number refers to a previously opened device channel.
The command number holds the number of the IO command you wish to Do. This command
may be entered directly by name, using the EQU function explained earlier. You are warned to
take great care when using this instruction!</p>
<h3 class="command" id="i-dev-send">DEV SEND</h3>
<p><i>instruction: call a command using SendIO</i><br>
<b>Dev Send</b> channel number,command</p>
<p>
This calls the SendIO command from Exec, and runs your operation using the Amiga's multi-
tasking system. The new process will run invisibly in the background, and your AMOS
Professional program will continue from the next instruction immediately.</p>
<h3 class="command" id="fn-dev-check">DEV CHECK</h3>
<p><i>function: check status of a device with a CheckIO</i><br>
value=<b>Dev Check</b>(channel number)</p>
<p>
Use this function to perform a CheckIO on the specified channel. The resulting value is passed
back to AMOS Professional.</p>
<h3 class="command" id="i-dev-abort">DEV ABORT</h3>
<p><i>instruction: abort an IO operation</i><br>
<b>Dev Abort</b> channel number</p>
<p>
This instruction executes an AbortIO and a WaitIO command, clearing all pending action from
the specified device channel. It can be used to exit directly from a multi-tasking operation,
without waiting for it to complete.</p>
<h3 class="command" id="fn-dev-base">DEV BASE</h3>
<p><i>function: get base address of an IO structure</i><br>
address=<b>Dev Base</b>(channel number)</p>
<p>
This function returns the base address of the IO structure assigned to the current device. The
structure can now be manipulated directly, using the STRUC commands, as required.</p>
</section>
<footer>
<a href="11-04-multitasking.html" rel="prev">Multi-Tasking</a>
<a href="./">Contents</a>
<a href="14-appendix-g-command-index.html">Index</a>
<a href="12-01-monitor.html" rel="next">The Monitor</a>
</footer>
</body>
</html>