
















                       Music Quest Programmer's ToolKit



                              Turbo C++ Interface



                                  Version 4.2













                               September 5, 1991



                   Copyright 1988, 1990 by Music Quest, Inc.

All rights to the Music Quest Programmer's ToolKit are reserved.  No part of
the ToolKit may be reproduced, or distributed in any form, or distributed by
any means, or stored in a database or retrieval system without the prior
written permission of Music Quest, Inc.


























                               Table of Contents



Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    3

Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    3

ToolKit Functions - Overview  . . . . . . . . . . . . . . . . . . . . . .    5
     Using Different Memory Models  . . . . . . . . . . . . . . . . . . .    5
     The Basic Interface (MCCTKF.ASM) . . . . . . . . . . . . . . . . . .    5
     The Co-processor SLIH (MCCTKIH.ASM)  . . . . . . . . . . . . . . . .    6
     Timer Services (MCCTKCK.ASM) . . . . . . . . . . . . . . . . . . . .    7

ToolKit Functions - Description . . . . . . . . . . . . . . . . . . . . .    7
     ackn_efw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    8
     add_trq_time . . . . . . . . . . . . . . . . . . . . . . . . . . . .    8
     clear_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    9
     clock_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    9
     conductor_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . .    9
     coproc_slih  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   10
     cuepoint_efw . . . . . . . . . . . . . . . . . . . . . . . . . . . .   10
     end_trq  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   10
     mcc_close  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   11
     mcc_command  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   11
     mcc_flush  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   12
     mcc_get  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   12
     mcc_irq  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   12
     mcc_noslih . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   13
     mcc_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   13
     mcc_put  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   14
     mcc_receive  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   14
     mcc_reset  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   15
     mclk_init  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   15
     mclk_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   16
     mclk_stop  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   16
     measurend_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . .   17
     midi_clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   17
     playend_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   17
     realtime_efw . . . . . . . . . . . . . . . . . . . . . . . . . . . .   18
     rec_bytes  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   18
     rec_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   19
     rec_overflow . . . . . . . . . . . . . . . . . . . . . . . . . . . .   19
     recordend_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . .   20
     set_slih . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   20
     set_trq  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   21
     set_trq_time . . . . . . . . . . . . . . . . . . . . . . . . . . . .   21
     smpte_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   22
     spp_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   22
     strk_end_efw . . . . . . . . . . . . . . . . . . . . . . . . . . . .   23
     track_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   23











                               Turbo C++ ToolKit                        Page 3


Introduction

This document describes the Turbo C++ interface of the Music Quest
Programmer's ToolKit.  It is written with the assumption that the reader is
familiar with the Music Quest MIDI interface architecture (or the MPU-401
architecture).  It is organized into the following topics:

     Files
          Describes each of the files that comprise the Turbo C++ interface.

     ToolKit Functions - Overview
          Introduces you to the basic design and organization of the ToolKit
          functions and services.

     ToolKit Functions - Description
          Describes the interface to each ToolKit function.

     Using the Example Programs
          Discusses the example source code modules.


Files

The following files make up the Turbo C++ interface.

\PTK\TURBOCPP\TKXMPL.CPP
     The main program for the example program.  This file includes the
     routines for the hex trace and program change functions.

\PTK\TURBOCPP\TKXMPL.H
     This is the header file used by all of the other *.CPP files.

\PTK\TURBOCPP\TKXMPL.OBJ
     The compiled object code for TKXMPL.CPP.

\PTK\TURBOCPP\TKXMPL.TLK
     This is the LINK control file for the TKXMPL program.  Use it with the
     TLINK program to link all of the *.OBJ files together into an executable
     program.  It also shows you which ToolKit files you need to link together
     to form the Turbo C++ interface.

\PTK\TURBOCPP\TKXMPL.EXE
     The linked, executable file for the TKXMPL program.






                               Turbo C++ ToolKit                        Page 4



\PTK\TURBOCPP\TKITRACE.CPP
     The source code for the interpreted trace routine.  The interpreted trace
     routine displays a decoded MIDI data stream, much like the MIDI Starter
     System Trace Utility.  This code provides an excellent example of how to
     decode a MIDI data stream, as it deals with just about every aspect of
     MIDI.  This routine is called by TKXMPL.

\PTK\TURBOCPP\TKITRACE.OBJ
     The compiled object code for TKITRACE.CPP.

\PTK\TURBOCPP\MCCTKSEQ.CPP
     This file contains the source code for the record and play back routines. 
     Together they implement a rudimentary one-track sequencer.  These
     routines illustrate how to use the interface's record and play back
     functions.  The record and play routines are called from TKXMPL.

\PTK\TURBOCPP\MCCTKSEQ.OBJ
     The compiled object code for MCCTKSEQ.CPP.

\PTK\TURBOCPP\MQXSYNC.CPP
     This file contains the source code for the examples of functions that are
     unique to the MQX-32.  This includes Chase Lock Sync (Song Position
     Pointer) and SMPTE.

\PTK\TURBOCPP\MQXSYNC.OBJ
     The compiled object code for MQXSYNC.CPP.

\PTK\TURBOCPP\TKXMPL.PRJ
     This file is a Project definition file that can be used with the Turbo
     C++ Integrated Development Environment.  You will have to customize
     according to your directory structures.

\PTK\ASM\MCC.H
     This file contains definitions (#define) for all of the interface
     commands and prototype statements for all ToolKit functions.  It is
     included by all of the example source code files.  You should include it
     in any program your write.

\PTK\ASM\MCCTKF.ASM
     This is the TASM/MASM source file for the basic interface interface functions.

\PTK\ASM\MCCTKF.OBJ
     The assembled object code for MCCTKF.ASM (small model).

\PTK\ASM\MCCTKIH.ASM
     This file contains the source code for the interface co-processor mode
     second level interrupt handler.  The functions of this module greatly
     simplify using the interface's record and play back functions.

\PTK\ASM\MCCTKIH.OBJ
     The assembled object code for MCCTKIH.ASM (small model).

\PTK\ASM\MCCTKCK.ASM
     This file contains the source code for the timer services.  The timer
     services are implemented as an extension to the co-processor mode second







                               Turbo C++ ToolKit                        Page 5


     level interrupt handler (MCCTKIH).  The timer services facilitate using
     the interface's clock.

\PTK\ASM\MCCTKCK.OBJ
     The assembled object code for MCCTKCK.ASM (small model).


ToolKit Functions - Overview

The Turbo C++ ToolKit is divided into three distinct groups of functions.


              +--------------------------+
              |      Timer Services      |
            +-+--------------------------+-+
            |      Co-processor SLIH       |
          +-+------------------------------+-+
          |         Basic Interface          |
          +----------------------------------+


     Basic interface:  The basic interface module provides services to send
     commands to the interface, to send data, and to receive data from the
     interface.

     Co-processor mode SLIH:  The co-processor SLIH (second level interrupt
     handler) is an installable extension to the basic interface.  It provides
     functions specifically for the interface's co-processor mode of
     operation.

     Timer services:  The timer services module provides a set of functions
     that allow PC software to exploit the interface's clock.  These services
     allow the programmer to establish a "count down timer" (sometimes
     referred to as an interval timer).  When the count down timer expires,
     timer services notify the "owner" of the timer.

Combined, these services facilitate the development of just about any MIDI
software function.  In fact, these services are the nucleus of the MIDI
Starter System software.


Using Different Memory Models

All of the *.OBJ files on the ToolKit diskette were compiled using the SMALL
memory model.  The small model is adequate for most applications.  However,
you can recompile all of the ToolKit *.CPP files under another model.  For
example, if you want to work in the LARGE model, you can recompile the *.CPP
files and link them together with the large model interface files in the \PTK\ASM\
directory (the last letter of the file name will be L).


The Basic Interface (MCCTKF.ASM)

The basic interface services allow you to send commands and data to the
interface, and to receive data from the interface.  The TKXMPL.CPP source file
illustrates how to use the basic services.  In pseudo code terms, you use the
basic services as follows:






                               Turbo C++ ToolKit                        Page 6



     1.   Call mcc_open to initialize basic services.  During initialization,
          the interface is reset to the power-on state.  It is checked to
          verify that the interface is at the designated I/O address and
          interrupt level.  A first level interrupt handler (FLIH) is
          installed to field all interrupts from the interface.  A default
          second level interrupt handler (SLIH) is installed as an extension
          to the FLIH.

     2.   Use the set_slih service to establish a second level interrupt
          handler (SLIH).  The SLIH is an extension of the FLIH.  Each time an
          interrupt occurs, the FLIH reads the incoming data from the
          interface and passes it to the SLIH.  

          Two SLIHs are included in the basic interface.  The mcc_receive SLIH
          stores each incoming data byte in a circular receive buffer.  You
          retrieve data bytes from the receive buffer through the mcc_get
          function.  The no_slih SLIH is a stub.  It throws away everything
          that is received.  This is a very useful function, when you are not
          expecting anything from the interface, and do no want to be bothered
          with any incoming data (eg. in UART mode where everything passes
          directly through the interface).

          Programmer's note:  The size of the circular receive buffer is fixed
          by the "buffsize" equate in MCCTKF.ASM.  If you want a different
          size receive buffer, change this value accordingly.

     3.   Use the mcc_command function to send commands to the interface.  Use
          the mcc_put function to send command operands to the interface.

     4.   Use the mcc_put and mcc_get functions to send and receive data. 
          Remember that the mcc_get function works ONLY when the mcc_receive
          SLIH is installed as the current SLIH.

     5.   When the program completes execution, invoke the mcc_close service. 
          This service resets the interface to power-on state and removes the
          FLIH.  NEVER use mcc_open without mcc_close.  Otherwise, there is a
          high probability that your system will hang on the next interrupt
          from the interface.


The Co-processor SLIH (MCCTKIH.ASM) 

The interface runs in two modes: co-processor mode (intelligent) or pass-
through (UART).  In co-processor mode, the interface sends a stream of data to
the PC.  The stream may contain time-stamped recording events, clock to PC
messages, track data requests, conductor data requests, and several other
interface-PC messages.  Decoding the interface-PC data stream is a difficult
task, but it must be done in order to fully utilize the interface.

The coproc_slih routine does most of the work for you, leaving you to write
the important part of the program.  This SLIH interprets the incoming
interface data stream, translating the stream into more comprehensible
concepts.  For example, incoming time-stamped events are stored in a recording
buffer.  Messages that are really interrupt notifications are turned into
Event Flag Words (EFWs).  An EFW is essentially a "mark on the wall" that the
coproc_slih sets when something occurs.






                               Turbo C++ ToolKit                        Page 7



A good example of an EFW is the conductor track EFW.  This EFW is set whenever
the co-processor SLIH receives a Conductor Data Request message.  The
conductor_efw function interrogates the conductor track EFW, returning its
current status.  When the EFW is set, you know you must respond by sending the
interface a new conductor event.

To install the co-processor SLIH, use the set_slih service, specifying
coproc_slih as the new SLIH.

To set up the coproc_slih for recording, you must use the rec_init function to
tell the location of the recording buffer and its size.  When recording has
ended, you can use the rec_bytes function to determine how many bytes of the
recording track were actually used.

The MCCTKSEQ.CPP source file illustrates how to set up coproc_slih for
recording and playback, and how to use many of the EFWs.


Timer Services (MCCTKCK.ASM)

The timer services use the interface's clock to PC message to implement
multiple interval timers.  Programmers who are familiar with mainframe
operating systems will quickly recognize the origin of these services.

The central concept of the timer service is the TRQ or timer request.  A TRQ
is a count down, interval timer.  When you establish a TRQ, you specify a
number of interface clock ticks.  Timer services uses the clock to PC message
to decrement the TRQ.  When the TRQ tick count reaches zero, the TRQ
"expires", and an event flag word, associated with the TRQ, is set.  After
establishing the TRQ, the program merely checks the EFW to see if the TRQ has
expired.

Before using the timer services, you must use the mclk_init function to
specify the granularity of clock to PC messages.  The granularity is the
number of clock ticks that should be counted for every clock to PC message. 
For example, if the granularity is 4, then every clock to PC message is
counted as 4 clock ticks, meaning that all active TRQs are decremented by 4.

After initializing timer services, you can use the mclk_start and mclk_stop
functions to start and stop the clock to PC messages.

Programmer's note:  The timer services are implemented as an extension to the
co-processor SLIH.  Therefore, to use the timer services, you must link in the
object code file MCCTKIH.OBJ, and establish coproc_slih as the current SLIH,
even if you don't use any other co-processor functions.



ToolKit Functions - Description

This section describes each ToolKit function, in terms of its interface
requirements.  Functions are presented in alphabetical order for ease of
reference.  Each function is described as follows:

-----------------------------------------------------------------------------
function_name






                               Turbo C++ ToolKit                        Page 8


-----------------------------------------------------------------------------
     Name                The function's name and one line description.

     Usage               Defines the function's invocation syntax and
                         parameter requirements.

     Related functions   Names any functions that are related to this
                         function.

     Description         Describes what the function does, the expected format
                         and values of parameters, and any other details you
                         need to know to be able to use the function.

     Returned value      Describes the value that the function returns, if it
                         returns a value.

     Source file         Name of the source file where the function is
                         implemented.

-----------------------------------------------------------------------------
ackn_efw
-----------------------------------------------------------------------------
     Name                ackn_efw - test the command acknowledge flag word.

     Usage               int ackn_efw();

     Related functions   mcc_command

     Description         This function returns the current state of the
                         command acknowledge EFW.  The EFW is reset after its
                         state is returned.  The command acknowledge EFW is
                         set when the co-processor SLIH receives a command
                         acknowledge message.

     Returned value      0 = EFW not set, acknowledge not received.
                         1 = EFW set, acknowledge received.

     Source file         \PTK\ASM\MCCTKF.ASM

-----------------------------------------------------------------------------
add_trq_time
-----------------------------------------------------------------------------
     Name                add_trq_time - add ticks to a TRQ.

     Usage               void add_trq_time(int trqhandle, int ticks);

     Related functions   set_trq, set_trq_time

     Description         Adds the value "ticks" to the TRQ identified by the
                         TRQ handle "trqhandle".  If you are concerned that a
                         TRQ may lose track of ticks, use this function
                         instead of set_trq_time to establish a new TRQ time
                         value.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKCK.ASM






                               Turbo C++ ToolKit                        Page 9




-----------------------------------------------------------------------------
clear_efw
-----------------------------------------------------------------------------
     Name                clear_efw - clear/reset an event flag word.

     Usage               void clear_efw(int *efw);

     Related functions   set_trq

     Description         This function provides a guaranteed safe way to reset
                         an EFW assigned to a TRQ.  Essentially, clear_efw
                         goes into disabled state, clears the TRQ, re-enables,
                         and returns.  Once a TRQ is set, this is the only
                         safe way to clear its EFW.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKCK.ASM


-----------------------------------------------------------------------------
clock_efw
-----------------------------------------------------------------------------
     Name                clock_efw - return the status of the clock to PC
                         message EFW.

     Usage               int clock_efw();

     Related functions   None.

     Description         Returns the current value of the clock to PC EFW. 
                         This EFW is set every time the co-processor SLIH
                         receives a clock to PC message.  If the EFW is set,
                         it is cleared before returning.

     Returned value      0 = EFW not set.
                         1 = EFW set.

     Source file         \PTK\ASM\MCCTKIH.ASM


-----------------------------------------------------------------------------
conductor_efw
-----------------------------------------------------------------------------
     Name                conductor_efw - return the status of the conductor
                         data request EFW.

     Usage               int conductor_efw();

     Related functions   None.

     Description         Returns the current value of the conductor track EFW. 
                         The CDR EFW is set every time a CDR is received from
                         the interface.  If the EFW is set, it is cleared
                         before returning.






                               Turbo C++ ToolKit                       Page 10



     Returned value      0 = CDR EFW not set.
                         1 = CDR EFW set.

     Source file         \PTK\ASM\MCCTKIH.ASM


-----------------------------------------------------------------------------
coproc_slih
-----------------------------------------------------------------------------
     Name                coproc_slih - co-processor mode second level
                         interrupt handler.

     Usage               void coproc_slih();
                         set_slih(&coproc_slih);

     Related functions   set_slih.

     Description         This function is not directly callable from C++.  It
                         is the SLIH for co-processor mode.  To install
                         coproc_slih as the current SLIH, you pass its address
                         to the set_slih function.  

     Returned value      None.

     Source file         \PTK\ASM\MCCTKIH.ASM


-----------------------------------------------------------------------------
cuepoint_efw
-----------------------------------------------------------------------------
     Name                cuepoint_efw - returns the current status of the
                         SMPTE cue point EFW.

     Usage               int cuepoint_efw();

     Related functions   smpte_efw.

     Description         This function returns the current status of the SMPTE
                         cue point EFW.  This EFW is set when the co-proc SLIH
                         receives the Cue Point system message.  It inidcates
                         that the MQX-32 has detected that the current SMPTE
                         frame address is equal to or greater than the active
                         cue point frame address.  If the EFW is set, it is
                         cleared before returning.

     Returned value      0 = EFW not set.
                         1 = EFW set.

     Source file         \PTK\ASM\MCCTKIH.ASM

-----------------------------------------------------------------------------
end_trq
-----------------------------------------------------------------------------
     Name                end_trq - end/delete an existing TRQ.

     Usage               void end_trq(int trqhandle);






                               Turbo C++ ToolKit                       Page 11



     Related functions   set_trq.

     Description         The end_trq function is complimentary to the set_trq
                         function.  It deletes a TRQ that had been previously
                         created via set_trq.  The value trqhandle identifies
                         the TRQ to be deleted.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKCK.ASM


-----------------------------------------------------------------------------
mcc_close
-----------------------------------------------------------------------------
     Name                mcc_close - close basic interface services.

     Usage               void mcc_close();

     Related functions   mcc_open.

     Description         The mcc_close function is the complimentary function
                         to mcc_open.  It closes the basic interrupt services
                         by resetting the interface and removing the first
                         level interrupt handler.  After executing mcc_slih,
                         none of the interface ToolKit functions are
                         available, until mcc_open is used to re-initialize
                         the ToolKit.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKF.ASM


-----------------------------------------------------------------------------
mcc_command
-----------------------------------------------------------------------------
     Name                mcc_command - send a command to the interface.

     Usage               int mcc_command(int cmd);

     Related functions   mcc_put, set_slih.

     Description         This function sends a command to the interface,
                         according to the protocol for sending commands. 
                         After the command is sent, mcc_command waits for the
                         corresponding command acknowledge from the interface. 
                         Any data received from the interface that is not the
                         acknowledge is sent to the current SLIH.  Therefore,
                         you should be sure that the current SLIH is capable
                         of fielding any interface messages that may arrive
                         while mcc_command is waiting for the acknowledge.

                         Use the mcc_put function to send command operands.








                               Turbo C++ ToolKit                       Page 12


     Returned value      0 = interface not ready to receive a command or the
                         command acknowledge did not arrive.
                         1 = command sent and acknowledge received.

     Source file         \PTK\ASM\MCCTKF.ASM


-----------------------------------------------------------------------------
mcc_flush
-----------------------------------------------------------------------------
     Name                mcc_flush - flush the contents of the receive buffer.

     Usage               void mcc_flush();

     Related functions   set_slih, mcc_receive, mcc_get, mcc_noslih.

     Description         This function flushes all queued data bytes from the
                         receive buffer that is managed by the mcc_receive
                         SLIH.  This is particularly useful in UART mode to
                         clear unwanted data (such as active sensing bytes)
                         from the receive buffer.

                         An alternative to worrying about unwanted data
                         accumulating in the receive buffer is to install
                         mcc_noslih as the current SLIH, whenever you do not
                         want any incoming data.  The mcc_noslih routine
                         discards everything that it receives.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKF.ASM


-----------------------------------------------------------------------------
mcc_get
-----------------------------------------------------------------------------
     Name                mcc_get - get the next data byte from the receive
                         buffer.

     Usage               int mcc_get();

     Related functions   mcc_receive, set_slih.

     Description         This function attempts to get the next data byte from
                         the receive buffer managed by the mcc_receive SLIH. 
                         If no data byte is available, it returns failure.

     Returned value      -1 = no data byte available.
                         0-0xFF = actual data byte obtained from the receive
                         buffer.

     Source file         \PTK\ASM\MCCTKF.ASM


-----------------------------------------------------------------------------
mcc_irq







                               Turbo C++ ToolKit                       Page 13


----------------------------------------------------------------------------
-

     Name                mcc_irq - determine the IRQ level being used by the
                         interface.

     Usage               int mcc_irq(int ioaddr);

     Related functions   mcc_open.

     Description         This function determines the interrupt request level
                         being used by the interface.  The value ioaddr,
                         specifies the base I/O address of the interface
                         (typically 0x330).  It is strongly recommended that
                         you use this function in every program, because it
                         makes your program independent of most of the
                         switch/jump selections on Music Quest interfaces.

     Returned value      0 = unable to determine IRQ level.  The most freqeunt
                         causes of failure are:

                              - no interface installed. 
                              - incorrect base I/O address.
                              - unable to reset the interface to the power-on
                              state.

                         1-7 = IRQ level being used by the interface.

     Source file         \PTK\ASM\MCCTKF.ASM


-----------------------------------------------------------------------------
mcc_noslih
-----------------------------------------------------------------------------
     Name                mcc_noslih - dummy second level interrupt handler.

     Usage               void mcc_slih();
                         set_slih(mcc_slih);

     Related functions   set_slih.

     Description         This function is not directly callable from C++.  It
                         is a "dummy" SLIH that can be established by passing
                         its address to the set_slih function.  When
                         mcc_noslih is in effect, all data bytes received from
                         the interface are discarded.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKF.ASM


-----------------------------------------------------------------------------
mcc_open
-----------------------------------------------------------------------------
     Name                mcc_open - initialize the basic ToolKit services.







                               Turbo C++ ToolKit                       Page 14


     Usage               int mcc_open(int ioaddr, int irqlevel);

     Related functions   mcc_close.

     Description         This function initializes the ToolKit services, much
                         like opening a file initializes I/O services for the
                         file.  The value ioaddr, specifies the base I/O
                         address of the interface (typically 0x330), while the
                         value  irqlevel specifies the interrupt level
                         assigned to the interface.  When mcc_open is
                         executed, it takes the following actions:

                         1.   Records the I/O address for use by other ToolKit
                              functions.

                         2.   Establishes a first level interrupt handler at
                              the specified interrupt level.

                         3.   Resets the interface to the power-on state.

                         4.   Attempts to verify that the interface is really
                              installed at the specified base I/O address and
                              interrupt level.

     Returned value      0 = initialization failure.  Causes of failure can
                         be:

                              - no interface installed. 
                              - incorrect base I/O address.
                              - incorrect interrupt level.
                              - unable to reset the interface to the power-on
                              state.

                         1 = successful initialization.

     Source file         \PTK\ASM\MCCTKF.ASM


-----------------------------------------------------------------------------
mcc_put
-----------------------------------------------------------------------------
     Name                mcc_put - send a data byte to the interface.

     Usage               void mcc_put(char dbyte);

     Related functions   mcc_get, mcc_command.

     Description         The data byte specified by the value dbyte is sent to
                         the interface.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKF.ASM


-----------------------------------------------------------------------------
mcc_receive






                               Turbo C++ ToolKit                       Page 15


-----------------------------------------------------------------------------
     Name                mcc_receive - basic second level interrupt handler.

     Usage               void mcc_receive();
                         set_slih(mcc_receive);

     Related functions   set_slih, no_slih, mcc_get, mcc_flush.

     Description         This function is not directly callable from C++.  It
                         is installed as the current second level interrupt
                         handler through the set_slih function.  When
                         mcc_receive is installed, it queues every incoming
                         data byte in a circular receive buffer.  Use the
                         mcc_get function to retrieve the data bytes from the
                         receive buffer.  Use the mc_flush routine to discard
                         all of the current contents of the receive buffer.

                         Programmer's note: The mcc_receive SLIH does not
                         perform buffer overflow checking.  Therefore, you
                         must be sure to use mcc_get frequently enough to keep
                         the receive buffer from overflowing.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKF.ASM


-----------------------------------------------------------------------------
mcc_reset
-----------------------------------------------------------------------------
     Name                mcc_reset - reset the interface to its power-on
                         state.

     Usage               void mcc_reset();

     Related functions   None.

     Description         This function resets the interface to its power-on
                         state.  After entering UART mode, this is the only
                         way to return the interface to co-processor mode.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKF.ASM


-----------------------------------------------------------------------------
mclk_init
-----------------------------------------------------------------------------
     Name                mclk_init - initialize the clock/timer services.

     Usage               void mclk_init(int ticvalue);

     Related functions   mclk_start, mclk_stop.

     Description         This function initializes the ToolKit timer services. 
                         The value ticvalue specifies the number of clock






                               Turbo C++ ToolKit                       Page 16


                         ticks that should be counted for every clock to PC
                         message that is received.  For example, if the clock
                         to PC frequency is set to produce a clock to PC
                         message every 4 interface clock ticks, then the
                         statement:

                              mclk_init(4);

                         correctly initializes the timer services. 

                         After initialization, use the mclk_start and
                         mclk_stop functions to start and stop the flow of
                         clock to PC messages.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKCK.ASM


-----------------------------------------------------------------------------
mclk_start
-----------------------------------------------------------------------------
     Name                mclk_start - start the flow of clock to PC messages.

     Usage               void mclk_start();

     Related functions   mclk_init, mclk_stop.

     Description         This command starts the flow of clock to PC messages
                         by sending an Enable Clock to PC command to the
                         interface.  The timer services only run when clock to
                         PC messages are flowing.

                         Use the mclk_stop function to stop the flow of clock
                         to PC messages, effectively suspending timer service
                         operation.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKCK.ASM


-----------------------------------------------------------------------------
mclk_stop
-----------------------------------------------------------------------------
     Name                mclk_stop - stop the flow of clock to PC messages.

     Usage               void mclk_stop();

     Related functions   mclk_init, mclk_start.

     Description         This function is the complement to the mclk_start
                         function.  It sends a Disable Clock to PC command to
                         the interface, thereby stopping the flow of clock to
                         PC messages.  Since TRQs are only decremented when a
                         clock to PC message arrives, this action effectively
                         suspends all TRQs.






                               Turbo C++ ToolKit                       Page 17



     Returned value      None.

     Source file         \PTK\ASM\MCCTKCK.ASM


-----------------------------------------------------------------------------
measurend_efw
-----------------------------------------------------------------------------
     Name                measurend_efw - return the status of the measure end
                         event flag word.

     Usage               int measurend_efw();

     Related functions   None.

     Description         Returns the current status of the measure end EFW. 
                         If the EFW is set, it is cleared.

     Returned value      0 = measure end EFW not set.
                         1 = measure end EFW set.

     Source file         \PTK\ASM\MCCTKIH.ASM


-----------------------------------------------------------------------------
midi_clock
-----------------------------------------------------------------------------
     Name                midi_clock - read, then clear, the timer services
                         tick counter.

     Usage               int midi_clock();

     Related functions   mclk_init, mclk_start, mclk_stop.

     Description         This function returns the current value of the tick
                         counter maintained by timer services.  Before
                         returning, the tick counter is reset.  As a result,
                         midi_clock always returns the number of interface
                         clock ticks that have been counted since the last
                         call.

                         As part of TRQ management, the timer services module
                         counts each clock to PC message by adding the tick
                         value (set by the mclk_init function) to the running
                         tick counter.  The midi_clock function allows you to
                         read this counter.

     Returned value      The current value of the running tick counter.

     Source file         \PTK\ASM\MCCTKCK.ASM


-----------------------------------------------------------------------------
playend_efw
-----------------------------------------------------------------------------







                               Turbo C++ ToolKit                       Page 18


     Name                playend_efw - return the status of the "all tracks
                         ended" event flag word.

     Usage               int playend_efw();

     Related functions   coproc_slih.

     Description         This function returns the current value of the all
                         play tracks ended EFW.  If the EFW is set, it is
                         cleared.  The playend EFW is set whenever the co-
                         processor slih receives an All Tracks Ended message
                         from the interface.

     Returned value      0 = EFW not set.
                         1 = EFW set.

     Source file         \PTK\ASM\MCCTKIH.ASM


-----------------------------------------------------------------------------
realtime_efw
-----------------------------------------------------------------------------
     Name                realtime_efw - return the status of the MIDI realtime
                         event flag word.

     Usage               int realtime_efw();

     Related functions   coproc_slih.

     Description         This function returns the current value of the MIDI
                         realtime EFW.  If the EFW is set, it is cleared.  The
                         realtime EFW is set whenever the co-processor slih
                         receives an interface system message containing a
                         MIDI start, continue, or stop 

     Returned value      0 = EFW not set.
                         0xFA = EFW set by MIDI start.
                         0xFB = EFW set by MIDI continue.
                         0xFC = EFW set by MIDI stop.

     Source file         \PTK\ASM\MCCTKIH.ASM


-----------------------------------------------------------------------------
rec_bytes
-----------------------------------------------------------------------------
     Name                rec_bytes - return the number of bytes used from the
                         recording buffer.

     Usage               int rec_bytes();

     Related functions   rec_init, coproc_slih.

     Description         The rec_init function passes a recording buffer to
                         the co-processor SLIH.  The rec_bytes function tells
                         you how many bytes have been used.  Typically, you
                         use the rec_bytes function after recording, to






                               Turbo C++ ToolKit                       Page 19


                         determine how many bytes of recording buffer space
                         were used.

     Returned value      The number of bytes used from the recording buffer.

     Source file         \PTK\ASM\MCCTKIH.ASM


-----------------------------------------------------------------------------
rec_init
-----------------------------------------------------------------------------
     Name                rec_init - initialize the co-processor SLIH for
                         recording.

     Usage               void rec_init(int buffseg, int buffoff, int
                         buffsize);

     Related functions   rec_bytes, rec_overflow, coproc_slih.

     Description         The rec_init function MUST be used to prior to
                         putting the interface into record mode.  The buffseg
                         and buffoff values specify the segment and offset
                         address of the recording buffer that is to be used by
                         the co-processor SLIH.  The buffsize value indicates
                         the size, in bytes, of the recording buffer.

                         Programmer's note:  Addressing wrap is not handled by
                         the recording functions.  Therefore, the value of
                         buffoff + buffsize cannot exceed 0xFFF.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKIH.ASM

-----------------------------------------------------------------------------
rec_overflow
-----------------------------------------------------------------------------
     Name                rec_overflow - return the status of the recording
                         buffer overflow event flag word.

     Usage               int rec_overflow();

     Related functions   rec_init, coproc_slih.

     Description         This function returns the current value of the
                         recording buffer overflow EFW.  This EFW is set when
                         the recording buffer is filled.

                         Programmer's note:  When the recording buffer fills,
                         the co-processor SLIH ends the recording buffer by
                         storing an End of Track message and setting the
                         record buffer overflow EFW.  Thus, even if the record
                         buffer does overflow, it can be played back
                         correctly, to the point where the overflow occurred.

     Returned value      0 = overflow has not occurred.
                         1 = recording buffer full.






                               Turbo C++ ToolKit                       Page 20



     Source file         \PTK\ASM\MCCTKIH.ASM

-----------------------------------------------------------------------------
recordend_efw
-----------------------------------------------------------------------------
     Name                recordend_efw - return the status of the recording
                         End of Track event flag word.

     Usage               int recordend_efw();

     Related functions   None.

     Description         The recordend_efw function returns the current status
                         of the End of Track EFW.  If the EFW is set, it is
                         cleared.  The End of Track EFW is set whenever the
                         co-processor SLIH receives a recording track end
                         message from the interface.  The interface sends this
                         message to the PC when the Stop Recording command
                         takes effect.

     Returned value      0 = End of Track not received.
                         1 = End of Track received.

     Source file         \PTK\ASM\MCCTKIH.ASM


-----------------------------------------------------------------------------
set_slih
-----------------------------------------------------------------------------
     Name                set_slih - set up a second level interrupt handler.

     Usage               void set_slih(void (*slihaddr)());

     Related functions   mcc_noslih, mcc_receive, coproc_slih.

     Description         The set_slih installs a given routine as a second
                         level interrupt handler.  The value slihaddr
                         specifies the address of the SLIH to be installed. 
                         The SLIH receives all incoming data bytes, as fielded
                         by the first level interrupt handler.

                         The following example installs mcc_receive as the
                         current SLIH.

                              int mcc_receive();
                              set_slih(mcc_receive);

                         Programmer's note:  You can write your own SLIH,
                         provided it meets the interface requirements defined
                         for mcc_receive and coproc_slih.  The source code for
                         these SLIHs documents that interface.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKF.ASM







                               Turbo C++ ToolKit                       Page 21



-----------------------------------------------------------------------------
set_trq
-----------------------------------------------------------------------------
     Name                set_trq - set up a timer request (TRQ).

     Usage               int set_trq(int *efw, int ticvalue);

     Related functions   end_trq, set_trq_time, add_trq_time, clear_efw.

     Description         The set_trq function creates a timer request or TRQ. 
                         The TRQ represents a count down timer that is managed
                         by the timer services module.  The value of ticvalue
                         specifies a number of interface clock ticks.  This
                         number is counted down each time a clock to PC
                         message is received.  When the value is less than or
                         equal to zero, the TRQ "expires".  When it expires,
                         the event flag word pointed to by efw is set to 0xFF.

                         Expiration of the TRQ time does not destroy the TRQ. 
                         The set_trq_time and add_trq_time functions can be
                         used to establish a new tick count, thus allowing the
                         TRQ to be used repetitively.

                         Use the clear_efw function to safely reset the EFW.

                         When you no longer need the TRQ, use the end_trq
                         function to delete it.

     Returned value      -1 = no TRQs available for use.  The timer services
                         module provides for 16 TRQs.  If you need more, you
                         can increase this number and re-assemble the
                         MCCTKCK.ASM file.

                         0-0x0FFF = Successful TRQ set up.  The returned value
                         is the "handle" that identifies the TRQ.  This handle
                         must be used with the other TRQ functions.

     Source file         \PTK\ASM\MCCTKCK.ASM


-----------------------------------------------------------------------------
set_trq_time
-----------------------------------------------------------------------------
     Name                set_trq_time - establish a new time value for an
                         existing TRQ.

     Usage               void set_trq_time(int trqhandle, int ticvalue);

     Related functions   set_trq, add_trq_time.

     Description         The set_trq_time function sets up a new timer value
                         for a TRQ previously created by the set_trq function. 
                         The value of ticvalue specifies the new time period,
                         in terms of interface clock ticks.  The trqhandle
                         value is the "handle" that identifies the TRQ being







                               Turbo C++ ToolKit                       Page 22


                         set.  The handle is the value returned by the set_trq
                         function.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKCK.ASM


-----------------------------------------------------------------------------
smpte_efw
-----------------------------------------------------------------------------
     Name                smpte_efw - return the status of the SMPTE frame
                         message event flag word.

     Usage               int smpte_efw(char smpte_fid[4]);

     Related functions   coproc_slih, strk_end_efw.

     Description         This function returns the current value of the SMPTE
                         frame message EFW.  If the EFW is set, it is cleared
                         and the last received SMPTE frame address is
                         returned.  The SMPTE frame message EFW is set
                         whenever the co-processor slih receives an MQX-32
                         system message ccontaining a SMPTE frame address.

     Returned value      0 = EFW not set, no SMPTE frame address returned.
                         1 = EFW set, last SMPTE frame address returned.

     Source file         \PTK\ASM\MCCTKIH.ASM


-----------------------------------------------------------------------------
spp_efw
-----------------------------------------------------------------------------
     Name                spp_efw - return the status of the Song Position
                         Pointer event flag word.

     Usage               int spp_efw(int *sppvalue);

     Related functions   coproc_slih.

     Description         This function returns the current value of the Song
                         Position Pointer EFW.  If the EFW is set, it is
                         cleared and the value of the SPP is returned.  The
                         SPP value specifies the new position in terms of
                         sixteenth notes (each SPP unit equals 6 MIDI clocks). 
                         The SPP EFW is set whenever the co-processor slih
                         receives an interface system message containing a
                         Song Position Pointer.

     Returned value      0 = EFW not set, no SPP value returned.
                         1 = EFW set, SPP value returned.

     Source file         \PTK\ASM\MCCTKIH.ASM









                               Turbo C++ ToolKit                       Page 23


-----------------------------------------------------------------------------
strk_end_efw
-----------------------------------------------------------------------------
     Name                strk_end_efw - return the status of the SMPTE Track
                         End event flag word.

     Usage               int strk_end_efw();

     Related functions   coproc_slih, smpte_efw.

     Description         This function returns the current value of the SMPTE
                         Track End EFW.  If the EFW is set, it is cleared. 
                         The SMPTE Track End EFW is set whenever the co-
                         processor slih receives an End of SMPTE Track message
                         from the MQX-32.  This message is sent when the MQX-
                         32 detects the end of SMPTE tape data. 

     Returned value      0 = EFW not set.
                         1 = EFW set.

     Source file         \PTK\ASM\MCCTKIH.ASM


-----------------------------------------------------------------------------
track_efw
-----------------------------------------------------------------------------
     Name                track_efw - return the status of a given play track's
                         event flag word.

     Usage               int track_efw(int track_number);

     Related functions   coproc_slih.

     Description         The track_efw function returns the current status of
                         the EFW for the play track identified by
                         track_number.  The value of track_number must be 0-7,
                         corresponding to play tracks 1-8.  If the EFW is set,
                         it is cleared before returning.

                         The co-processor SLIH sets a track's EFW every time
                         it receives a Track Data Request message from the
                         interface.

     Returned value      0 = no TDR received for this track.
                         1 = TDR received for this track.

     Source file         \PTK\ASM\MCCTKIH.ASM












