
















                       Music Quest Programmer's ToolKit



            Turbo Assembler and Microsoft Macro Assembler Interface



                                  Version 3.1













                                 April 8, 1990



                   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  . . . . . . . . . . . . . . . . . . . . . .    4
     Using the ASM ToolKit with Different Models and Languages  . . . . .    4
     The Basic Interface (MCCTKF.ASM) . . . . . . . . . . . . . . . . . .    5
     The Co-processor SLIH (MCCTKIH.ASM)  . . . . . . . . . . . . . . . .    6
     Timer Services (MCCTKCK.ASM) . . . . . . . . . . . . . . . . . . . .    6

ToolKit Functions - Description . . . . . . . . . . . . . . . . . . . . .    7
     _ackn_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    7
     _add_trq_time  . . . . . . . . . . . . . . . . . . . . . . . . . . .    8
     _clear_efw . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    8
     _clock_efw . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    8
     _conductor_efw . . . . . . . . . . . . . . . . . . . . . . . . . . .    9
     _coproc_slih . . . . . . . . . . . . . . . . . . . . . . . . . . . .    9
     _cuepoint_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . .   10
     _end_trq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   10
     _mcc_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   10
     _mcc_command . . . . . . . . . . . . . . . . . . . . . . . . . . . .   11
     _mcc_flush . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   11
     _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 . . . . . . . . . . . . . . . . . . . . . . . . . . .   16
     _midi_clock  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   17
     _playend_efw . . . . . . . . . . . . . . . . . . . . . . . . . . . .   17
     _realtime_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . .   18
     _rec_bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   18
     _rec_init  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   18
     _rec_overflow  . . . . . . . . . . . . . . . . . . . . . . . . . . .   19
     _recordend_efw . . . . . . . . . . . . . . . . . . . . . . . . . . .   19
     _set_slih  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   20
     _set_trq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   20
     _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 assembler language interface (referred to as the
ASM interface) of the 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 assembler 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.


Files

The following files make up the ASM interface.

\LIB\MCCTKF.ASM
     This is the ASM source file for the basic interface functions.

\LIB\MCCTKF.OBJ
\LIB\MCCTKFM.OBJ
\LIB\MCCTKFC.OBJ
\LIB\MCCTKFL.OBJ
\LIB\MCCTKFB.OBJ
     The assembled object code for MCCTKF.ASM.  The last character in the file
     name designates the memory model or language (none=small, M=medium,
     C=compact, L=large, B=QuickBasic).

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

\LIB\MCCTKIH.OBJ
\LIB\MCCTKIHM.OBJ
\LIB\MCCTKIHC.OBJ
\LIB\MCCTKIHL.OBJ
\LIB\MCCTKIHB.OBJ
     The assembled object code for MCCTKIH.ASM.  The last character in the
     file name designates the memory model or language (none=small, M=medium,
     C=compact, L=large, B=QuickBasic).

\LIB\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
     level interrupt handler (MCCTKIH).  The timer services facilitate using
     the interface's clock.










                                Turbo C ToolKit                         Page 4


\LIB\MCCTKCK.OBJ
\LIB\MCCTKCKM.OBJ
\LIB\MCCTKCKC.OBJ
\LIB\MCCTKCKL.OBJ
\LIB\MCCTKCKB.OBJ
     The assembled object code for MCCTKCK.ASM.  The last character in the
     file name designates the memory model or language (none=small, M=medium,
     C=compact, L=large, B=QuickBasic).


ToolKit Functions - Overview

The ASM 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 MIDI 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 interfaces'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 the ASM ToolKit with Different Models and Languages

The ASM ToolKit is designed for use with the small, medium, compact, and large
memory models.  The source code uses conditional assembly statements to
produce the correct code for a given model or language.  With the exception of
the Turboc Pascal interface, all other interfaces are generated by assembling
the three interface modules with different parameters.  If you want to modify
the interface modules or you need to reassemble them, you can do so with the
following invocations of the Turbo Assembler or Microsoft Assembler:

     MASM /Dmodel asmfile;
or
     TASM /Dmodel asmfile;






                                Turbo C ToolKit                         Page 5



You must substitute one of the following model/language designators for the
model parameter.

     _SMALL_   small model
     _MEDIUM_  medium model
     _COMPACT_ compact model
     _LARGE_   large model
     _QBASIC_  for Microsoft Quick Basic

For example,

     MASM /D_LARGE_ mcctkf;

will assemble the MCCTKF.ASM module for the large memory model.


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.  In pseudo code terms, you
use the basic services as follows:

     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.








                                Turbo C ToolKit                         Page 6


     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.

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.


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. 







                                Turbo C ToolKit                         Page 7


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 interTKIH.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
-----------------------------------------------------------------------------
     Name                The function's name and one line description.

     Usage               Defines the function's invocation sequence and
                         parameter requirements.  The usage specification is
                         intended to outline parameters, and the order the
                         parameters must be pushed onto the stack.  You may
                         find that the usage specification is not
                         syntactically correct ASM code.

     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.  All values are returned in AX.

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

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

     Usage               call _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.






                                Turbo C ToolKit                         Page 8



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

     Source file         \LIB\MCCTKF.ASM

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

     Usage               push ticks
                         push trqhandle
                         call _add_trq_time
                         add  sp,+4

     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         \LIB\MCCTKCK.ASM


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

     Usage               push offset efw
                         call _clear_efw
                         add  sp,+2

     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         \LIB\MCCTKCK.ASM


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







                                Turbo C ToolKit                         Page 9


     Usage               call _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         \LIB\MCCTKIH.ASM


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

     Usage               call _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.

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

     Source file         \LIB\MCCTKIH.ASM


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

     Usage               push offset _coproc_slih
                         call _set_slih
                         add  sp,+2

     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         \LIB\MCCTKIH.ASM







                                Turbo C ToolKit                        Page 10



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

     Usage               call _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         \LIB\MCCTKIH.ASM

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

     Usage               push trqhandle
                         call _end_trq
                         add  sp,+2

     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         \LIB\MCCTKCK.ASM


-----------------------------------------------------------------------------
_mcc_close
-----------------------------------------------------------------------------
     Name                _mcc_close - close basic interface services.

     Usage               call _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






                                Turbo C ToolKit                        Page 11


                         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         \LIB\MCCTKF.ASM


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

     Usage               push cmd
                         call _mcc_command
                         add  sp,+2

     Related functions   _mcc_put, _set_slih.

     Description         This function sends a command to the , 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.

     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         \LIB\MCCTKF.ASM


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

     Usage               call _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.








                                Turbo C ToolKit                        Page 12


                         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         \LIB\MCCTKF.ASM


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

     Usage               call _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         \LIB\MCCTKF.ASM

-----------------------------------------------------------------------------
_mcc_irq
-----------------------------------------------------------------------------
     Name                _mcc_irq - determine the IRQ being used by the
                         interface.

     Usage               push ioaddr
                         call _mcc_irq
                         add  sp,+2

     Related functions   _mcc_open

     Description         This function determines which interrupt level is
                         being used by the interface.  The value ioaddr
                         specifies the base I/O address of the (typically
                         0x330).  This function should be used by every
                         program so that the program is independent of the IRQ
                         assignment.

     Returned value      0 = unable to find the MIDI interface.  Causes of
                         failure can be:

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






                                Turbo C ToolKit                        Page 13



                         1-7 = IRQ level being used by interface.

     Source file         \LIB\MCCTKF.ASM


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

     Usage               push offset _mcc_slih
                         call _set_slih
                         add  sp,+2

     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         \LIB\MCCTKF.ASM


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

     Usage               push irqlevel
                         push ioaddr
                         call _mcc_open
                         add  sp,+4

     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 MIDI 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.








                                Turbo C ToolKit                        Page 14


                         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         \LIB\MCCTKF.ASM


-----------------------------------------------------------------------------
_mcc_put
-----------------------------------------------------------------------------
     Name                _mcc_put - send a data byte to the card.

     Usage               push dbyte
                         call _mcc_put
                         add  sp,+2

     Related functions   _mcc_get, _mcc_command.

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

     Returned value      None.

     Source file         \LIB\MCCTKF.ASM


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

     Usage               push offset _mcc_receive
                         call _set_slih
                         add  sp,+2

     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.







                                Turbo C ToolKit                        Page 15


                         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         \LIB\MCCTKF.ASM


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

     Usage               call _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         \LIB\MCCTKF.ASM


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

     Usage               push ticvalue
                         call _mclk_init
                         add  sp,+2

     Related functions   _mclk_start, _mclk_stop.

     Description         This function initializes the ToolKit timer services. 
                         The value ticvalue specifies the number of clock
                         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.






                                Turbo C ToolKit                        Page 16



     Source file         \LIB\MCCTKCK.ASM


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

     Usage               call _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 card. 
                         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         \LIB\MCCTKCK.ASM


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

     Usage               call _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 , 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.

     Returned value      None.

     Source file         \LIB\MCCTKCK.ASM


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

     Usage               call _measurend_efw

     Related functions   None.






                                Turbo C ToolKit                        Page 17



     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         \LIB\MCCTKIH.ASM


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

     Usage               call _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         \LIB\MCCTKCK.ASM


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

     Usage               call _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 card.

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







                                Turbo C ToolKit                        Page 18


     Source file         \LIB\MCCTKIH.ASM


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

     Usage               call _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         \LIB\MCCTKIH.ASM


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

     Usage               call _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
                         determine how many bytes of recording buffer space
                         were used.

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

     Source file         \LIB\MCCTKIH.ASM


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

     Usage               push buffsize
                         push buffoff






                                Turbo C ToolKit                        Page 19


                         push buffseg
                         call _rec_init
                         add  sp,+6

     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         \LIB\MCCTKIH.ASM

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

     Usage               call _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.

     Source file         \LIB\MCCTKIH.ASM

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

     Usage               call _recordend_efw

     Related functions   None.







                                Turbo C ToolKit                        Page 20


     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 card.  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         \LIB\MCCTKIH.ASM


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

     Usage               push slihaddr
                         call _set_slih
                         add  sp,+2

     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         \LIB\MCCTKF.ASM


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

     Usage               push ticvalue
                         push offset efw
                         call _set_trq
                         add  sp,+4







                                Turbo C ToolKit                        Page 21


     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         \LIB\MCCTKCK.ASM


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

     Usage               push ticvalue
                         push trqhandle
                         call _set_trq_time
                         add  sp,+4

     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 set.  The handle is the value returned by
                         the _set_trq function.

     Returned value      None.

     Source file         \LIB\MCCTKCK.ASM






                                Turbo C ToolKit                        Page 22




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

     Usage               push offset smpte_fid
                         call _smpte_efw
                         add sp,+2

     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_fid parameter is a 4-byte data area).  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         \LIB\MCCTKIH.ASM


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

     Usage               push offset sppvalue
                         call _spp_efw
                         add sp,+2

     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
                         paramter sppvalue is a word).  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         \LIB\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               call _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         \LIB\MCCTKIH.ASM


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

     Usage               push track_number
                         call _track_efw
                         add  sp,+2

     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 card.

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

     Source file         \LIB\MCCTKIH.ASM









