Accessing a device requires obtaining a message port, allocating memory
for a specialized message packet called an I/O request, setting a pointer
to the message port in the I/O request, and finally, establishing the link
to the device itself by opening it.  An example of how to do this will be
provided later in this chapter.

The message port is used by the device to return messages to you.  A
message port is obtained by calling the createmsgport() or createport()
function.  You must delete the message port when you are finished by
calling the deletemsgport() or deleteport() function.

For pre-V36 versions of the operating system (before Release 2.0), use the
amiga.lib functions createport() and deleteport(); for v36 and higher, use
the Exec functions createmsgport() and deletemsgport(). createport() and
deleteport() are upward compatible, you can use them with v36/v37;
createmsgport() and deletemsgport() are not backward compatible, however.

The I/O request is used to send commands and data from your application to
the device.  The I/O request consists of fields used to hold the command
you wish to execute and any parameters it requires.  You set up the fields
with the appropriate information and send it to the device by using Exec
I/O functions.

At least four methods exist for creating an I/O request:

   *  Declaring it as a structure.  The memory required will be allocated
      at compile time.

   *  Declaring it as a pointer and calling the allocmem() function.  you
      will have to call the freemem() function to release the memory when
      you are done.

   *  Declaring it as a pointer and calling the createextio() function.
      This function not only allocates the memory for the request, it also
      puts the message port in the I/O request.  You will have to call the
      deleteextio() function to delete the i/o request when you are done.
      This is the pre-V36 method (used in 1.3 and earlier versions of the
      operating system), but is upward compatible.

   *  Declaring it as a pointer and calling the createiorequest() function.
      This function not only allocates the memory for the request, it also
      puts the message port in the I/O request.  You will have to call the
      deleteiorequest() function to delete the i/o request when you are
      done.  This is the V36/V37 method; it is not backwards compatible.

The message port pointer in the I/O request tells the device where to
respond with messages for your application.  You must set a pointer to the
message port in the I/O request if you declare it as a structure or
allocate memory for it using allocmem().

The device is opened by calling the opendevice() function.  in addition to
establishing the link to the device, OpenDevice() also initializes fields
in the I/O request.  OpenDevice() has this format:

  return = OpenDevice(device_name,unit_number,
                     (struct IORequest *)IORequest,flags)

where:

   *  device_name is one of the following NULL-terminated strings for
      system devices:

        audio.device        keyboard.device    serial.device
        clipboard.device    narrator.device    timer.device
        console.device      parallel.device    trackdisk.device
        gameport.device     printer.device     input.device
        scsi.device

   *  unit_number refers to one of the logical units of the device. Devices
      with one unit always use unit 0.  Multiple unit devices like the
      trackdisk device and the timer device use the different units for
      specific purposes.  The device chapters discuss the units in detail.

   *  iorequest is the structure discussed above.  some of the devices have
      their own I/O requests defined in their include files and others use
      standard I/O requests, (iostdreq).  the device chapters list the i/o
      request that each device requires.

   *  flags are bits set to indicate options for some of the devices.  This
      field is set to zero for devices which don't accept options when they
      are opened.  The device chapters and autodocs list the flags values
      and uses.

   *  return is an indication of whether the opendevice() was successful
      with zero indicating success.  Never assume that a device will
      successfully open.  Check the return value and act accordingly.

   Zero Equals Success for OpenDevice().
   -------------------------------------
   Unlike most Amiga system functions, opendevice() returns zero for
   success and a device-specific error value for failure.