                        Generic MPU-401 Device Driver
                 Copyright (C) 1990-1993, Delta Music Systems


                           Developer Instructions



Introduction

The generic MPU-401 Device Driver is for MIDI interfaces in AT compatible
systems with an ISA bus.  It was written under OS/2 1.21, and has been
tested under 1.21, 1.3, 2.0, and 2.1(beta).

The device driver supports the complete set of MPU commands.  Extensions
specific to OS/2 have been added, and are available through the DMS MPU
Interface Library.  If you are interested in purchasing the library, please
use the order form (see the file ORDER.FRM).

This software is not in the public domain; however, it may be distributed
freely so long as it is not bundled with any commercial product, or any fee
beyond duplication and shipping is charged for distribution.  If you would
like information on distributing this software with another product, please
contact us at the address below.

Delta Music Systems
2615 Ginghamsburg-Frederick Rd.
Tipp City, OH  45371

If you would like to be notified of future products from Delta Music Systems,
please fill out and return the registration form (see the file REGISTER.FRM).



Developer Instructions

The generic MPU-401 device driver is accessed through the DOS API provided
by OS/2.  The published interface includes only those functions that provide
complete MPU-401 compatibility.  Additional functionality, such as blocking
reads and packet-oriented messages, is available through the DMS MPU Interface
Library.

The following table lists the published interface to the generic MPU-401
device driver.  All numbers are in hexadecimal unless otherwise indicated.

Please take careful note of the changes for the OS/2 2.x Device Interface.

****************************************************************************

OS/2 1.x:
USHORT DosOpen("MPU401",
               PHFILE  phf,
               PUSHORT pusAction, 
               0L, 
               FILE_NORMAL,
               FILE_OPEN, 
               OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYREADWRITE,
               0L)

phf          The address of the variable that receives the handle returned by
             OS/2.  This handle will be used for all other functions.

pusAction    This variable is not utilized, but must still be present.

Return Value

The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:

     ERROR_ACCESS_DENIED
     ERROR_FILE_NOT_FOUND
     ERROR_INVALID_ACCESS
     ERROR_INVALID_PARAMETER
     ERROR_OPEN_FAILED
     ERROR_PATH_NOT_FOUND
     ERROR_SHARING_BUFFER_EXCEEDED
     ERROR_SHARING_VIOLATION
     ERROR_TOO_MANY_OPEN_FILES

****************************************************************************

USHORT DosClose(HFILE hf)

hf         Identifies the device to close. This handle must have been created
           by using the DosOpen function.

Return Value

The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:

     ERROR_ACCESS_DENIED
     ERROR_FILE_NOT_FOUND
     ERROR_INVALID_HANDLE

****************************************************************************

USHORT DosRead(HFILE hf, BYTE *Buffer, USHORT BufSize, PUSHORT BytesRead)

The DosRead function reads up to a specified number of bytes of data from a
file into a buffer. The function may read fewer than the specified number of
bytes if it reaches the end of the file.

hf            Identifies the device to be read. This handle must have been
              created by using the DosOpen function.

Buffer        Points to the buffer that receives the data.

BufSize       Specifies the size of the buffer.

pcbBytesRead  Points to the variable that receives the number of bytes read
              from the file.  If no data has been received by the interface,
              this value may be zero.

Return Value

The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:

     ERROR_ACCESS_DENIED
     ERROR_INVALID_HANDLE

****************************************************************************

USHORT DosWrite(HFILE hf, BYTE *Buffer, USHORT BufSize, PUSHORT pBytesWritten)

hf             Identifies the device that receives the data. This handle
               must have been created by using the DosOpen function.

Buffer         Points to the buffer that contains the data to write.

BufSize        Specifies the size of the Buffer.

pBytesWritten  Points to the variable receiving the number of bytes written.

Return Value

The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:

     ERROR_ACCESS_DENIED
     ERROR_INVALID_HANDLE

****************************************************************************

USHORT DosDevIOCtl(PVOID  pvData,
                   PVOID  pvParms,
                   USHORT usFunction,
                   USHORT usCategory,
                   HFILE  hf)

pvData      Points to a buffer that contains the length of the Parm buffer
                                                for variable length messages.

pvParms     Points to a buffer that contains any data to be transmitted, or
            to store data being returned.  The length of this buffer is not
            checked by the device driver.

usFunction  the function number is equivalent to the MPU command number.
            For example, to reset the device, use a function code of FF.

usCategory  Category 80 is used for MPU commands

hf          Identifies the device that receives the command. This handle
            must have been created by using the DosOpen function.

Return Value

In addition to the system error values, the DosDevIOCtl function returns
device driver return-value information.

The error value may be one of the following:

     ERROR_INVALID_CATEGORY

****************************************************************************
