
















                       Music Quest Programmer's ToolKit



                      Turbo Pascal 4.0 and 5.0 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  . . . . . . . . . . . . . . . . . . . . . .    4
     The Basic Interface (MCCTKFP.ASM)  . . . . . . . . . . . . . . . . .    5
     The Co-processor SLIH (MCCTKIHP.ASM) . . . . . . . . . . . . . . . .    6
     Timer Services (MCCTKCKP.ASM)  . . . . . . . . . . . . . . . . . . .    6

Working from the Example Program  . . . . . . . . . . . . . . . . . . . .    7

ToolKit Functions - Description . . . . . . . . . . . . . . . . . . . . .    7
     _ackn_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    8
     _add_trq_time  . . . . . . . . . . . . . . . . . . . . . . . . . . .    8
     _clear_efw . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    8
     _clock_efw . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    9
     _conductor_efw . . . . . . . . . . . . . . . . . . . . . . . . . . .    9
     _cuepoint_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . .    9
     _end_trq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   10
     _mcc_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   10
     _mcc_command . . . . . . . . . . . . . . . . . . . . . . . . . . . .   11
     _mcc_flush . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   11
     _mcc_get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   12
     _mcc_irq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   12
     _mcc_open  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   13
     _mcc_put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   13
     _mcc_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   14
     _mcc__set_coprocslih . . . . . . . . . . . . . . . . . . . . . . . .   14
     _mcc__set_noslih . . . . . . . . . . . . . . . . . . . . . . . . . .   14
     _mcc__set_receiveslih  . . . . . . . . . . . . . . . . . . . . . . .   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_trq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   20
     _set_trq_time  . . . . . . . . . . . . . . . . . . . . . . . . . . .   21
     _smpte_efw . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   21
     _spp_efw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   21
     _strk_end_efw  . . . . . . . . . . . . . . . . . . . . . . . . . . .   22
     _track_efw . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   22











                       Turbo Pascal 4.0 and 5.0 ToolKit                 Page 3


Introduction

This document describes the Turbo Pascal interface of the MCC 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 Pascal
          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 Pascal interface.

\PTK\TURBOPAS\MCC.PAS
     The source code for the interface interface unit.  This source code
     combines the object code from the TASM interface files into a single
     Turbo Pascal Unit.  When you want to use the interface interfaqce
     routines, you must specify interface in a Uses statement.  See TKXMPL.PAS
     for an example.

\PTK\TURBOPAS\MCC.TPU
     The compiled objectd code for the interface interface, in Turbo Pascal
     Unit format.

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

\PTK\TURBOPAS\TKXMPL.EXE
     The compiled and linked executable file for the TKXMPL program.

\PTK\TURBOPAS\INTTRACE.PAS
     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\TURBOPAS\INTTRACE.TPU
     The compiled object code, in Turbo Pascal Unit format, for INTTRACE.PAS.

\PTK\TURBOPAS\MCCTKSP.PAS
     This file contains the source code for the record and play back routines. 
     Together they implement a rudimentary one-track sequencer.  These






                       Turbo Pascal 4.0 and 5.0 ToolKit                 Page 4


     routines illustrate how to use the interface's record and play back
     functions.  The record and play routines are called from TKXMPL.

\PTK\TURBOPAS\MCCTKSP.TPU
     The compiled object code, int Turbo Pascal Unit format, for MCCTKSP.PAS.

\PTK\TURBOPAS\MCCCONST.INC
     This file contains definitions (constants) for all of the interface
     commands.  It is included by all of the example source code files.  You
     should include it in any program your write, when you need to send
     commands to the interface.

\PTK\TURBOPAS\MCCTKFP.ASM
     This is the TASM source file for the basic interface interface functions.

\PTK\TURBOPAS\MCCTKFP.OBJ
     The assembled object code for MCCTKFP.ASM.

\PTK\TURBOPAS\MCCTKIHP.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\TURBOPAS\MCCTKIHP.OBJ
     The assembled object code for MCCTKIHP.ASM.

\PTK\TURBOPAS\MCCTKCKP.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 (MCCTKIHP).  The timer services facilitate using
     the interface's clock.

\PTK\TURBOPAS\MCCTKCKP.OBJ
     The assembled object code for MCCTKCKP.ASM.


ToolKit Functions - Overview

The Turbo Pascal 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







                       Turbo Pascal 4.0 and 5.0 ToolKit                 Page 5


     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.


The Basic Interface (MCCTKFP.ASM)

The basic interface services allow you to send commands and data to the
interface, and to receive data from the interface.  The TKXMPL.PAS source file
illustrates how to use the basic services.  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 MCCTKFP.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






                       Turbo Pascal 4.0 and 5.0 ToolKit                 Page 6


          a high probability that your system will hang on the next interrupt
          from the interface.


The Co-processor SLIH (MCCTKIHP.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.

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


Timer Services (MCCTKCKP.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 Pascal 4.0 and 5.0 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 MCCTKIHP.OBJ, and establish coproc_slih as the current SLIH,
even if you don't use any other co-processor functions.


Working from the Example Program

One way to develop your own software is to start with the example program
(TKXMPL) and its associated Pascal units.  If you wish to work this way, you
must compile the interface, INTTRACE, MCCTKSP, and MQXSYNC files first (to
produce *.TPU files).  Then, you can compile the TKXMPL file to produce an
executable program.



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


















                       Turbo Pascal 4.0 and 5.0 ToolKit                 Page 8


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

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

     Usage               function _ackn_efw: integer;

     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\TURBOPAS\MCCTKFP.ASM

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

     Usage               procedure _add_trq_time(trqhandle, ticks: integer);

     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\TURBOPAS\MCCTKCKP.ASM


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

     Usage               procedure _clear_efw(var efw: integer);

     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.






                       Turbo Pascal 4.0 and 5.0 ToolKit                 Page 9



     Returned value      None.

     Source file         \PTK\TURBOPAS\MCCTKCKP.ASM


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

     Usage               function _clock_efw: integer;

     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\TURBOPAS\MCCTKIHP.ASM


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

     Usage               function _conductor_efw: integer;

     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         \PTK\TURBOPAS\MCCTKIHP.ASM



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

     Usage               function _cuepoint_efw: integer;







                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 10


     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\TURBOPAS\MCCTKIHP.ASM

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

     Usage               procedure _end_trq(trqhandle: integer);

     Related functions   _set_trq.

     Description         The _end_trq procedure 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\TURBOPAS\MCCTKCKP.ASM


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

     Usage               procedure _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\TURBOPAS\MCCTKFP.ASM









                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 11


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

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

     Usage               function _mcc_command(cmd: integer): integer;

     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.

     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\TURBOPAS\MCCTKFP.ASM


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

     Usage               procedure _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\TURBOPAS\MCCTKFP.ASM








                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 12


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

     Usage               function _mcc_get: integer;

     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-$FF = actual data byte obtained from the receive
                         buffer.

     Source file         \PTK\TURBOPAS\MCCTKFP.ASM


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

     Usage               function _mcc_irq(ioaddr: integer): integer;

     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 interface
                         (typically $330).  It is strongly recommended that
                         you use this function in all programs, rather than
                         require the end user to determine how the interface
                         was installed.  This makes your programs independent
                         of most of the switch/jumper settings on Music Quest
                         interfaces.

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

                              - 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\TURBOPAS\MCCTKFP.ASM











                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 13


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

     Usage               function _mcc_open(ioaddr, irqlevel: integer):
                         integer;

     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 $330), 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\TURBOPAS\MCCTKFP.ASM


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

     Usage               procedure _mcc_put(dbyte: integer);

     Related functions   _mcc_get, _mcc_command.

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

     Returned value      None.






                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 14



     Source file         \PTK\TURBOPAS\MCCTKFP.ASM



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

     Usage               procedure _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\TURBOPAS\MCCTKFP.ASM


-----------------------------------------------------------------------------
_mcc__set_coprocslih
-----------------------------------------------------------------------------
     Name                _mcc__set_coprocslih - install co-processor mode
                         second level interrupt handler.

     Usage               procedure _mcc__set_coprocslih;

     Related functions   _mcc__set_receiveslih, _mcc__set_noslih.

     Description         This function installs the SLIH for co-processor mode
                         (coproc_slih). 

     Returned value      None.

     Source file         \PTK\TURBOPAS\MCCTKFP.ASM


-----------------------------------------------------------------------------
_mcc__set_noslih
-----------------------------------------------------------------------------
     Name                _mcc__set_noslih - install dummy second level
                         interrupt handler.

     Usage               procedure _mcc__set_noslih;

     Related functions   _mcc__set_coprocslih, _mcc__set_receiveslih.

     Description         This function installs a "do nothing" second level
                         interrupt handler.  When this interrupt handler is in
                         effect, all data bytes received from the interface
                         are discarded.







                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 15


     Returned value      None.

     Source file         \PTK\TURBOPAS\MCCTKFP.ASM


-----------------------------------------------------------------------------
_mcc__set_receiveslih
-----------------------------------------------------------------------------
     Name                _mcc__set_receiveslih - install basic second level
                         interrupt handler.

     Usage               procedure _mcc__set_receiveslih;

     Related functions   _mcc__set_noslih, _mcc__set_coprocslih, _mcc_get,
                         _mcc_flush.

     Description         This function installs the basic SLIH (_mcc_receive). 
                         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\TURBOPAS\MCCTKFP.ASM


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

     Usage               procedure _mclk_init(ticvalue: integer);

     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. 









                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 16


                         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\TURBOPAS\MCCTKCKP.ASM


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

     Usage               procedure _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\TURBOPAS\MCCTKCKP.ASM


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

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

     Returned value      None.

     Source file         \PTK\TURBOPAS\MCCTKCKP.ASM


-----------------------------------------------------------------------------
_measurend_efw
-----------------------------------------------------------------------------







                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 17


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

     Usage               function _measurend_efw: integer;

     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\TURBOPAS\MCCTKIHP.ASM


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

     Usage               function _midi_clock: integer;

     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\TURBOPAS\MCCTKCKP.ASM


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

     Usage               function _playend_efw: integer;

     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-






                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 18


                         processor slih receives an All Tracks Ended message
                         from the interface.

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

     Source file         \PTK\TURBOPAS\MCCTKIHP.ASM


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

     Usage               function _realtime_efw: integer;

     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.
                         $FA = EFW set by MIDI start.
                         $FB = EFW set by MIDI continue.
                         $FC = EFW set by MIDI stop.

     Source file         \PTK\TURBOPAS\MCCTKIHP.ASM


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

     Usagem              function _rec_bytes: integer;

     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         \PTK\TURBOPAS\MCCTKIHP.ASM


-----------------------------------------------------------------------------
_rec_init






                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 19


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

     Usage               procedure _rec_init(buffseg, buffoff, buffsize:
                         integer);

     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 $FFF.

     Returned value      None.

     Source file         \PTK\TURBOPAS\MCCTKIHP.ASM

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

     Usage               function _rec_overflow: integer;

     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         \PTK\TURBOPAS\MCCTKIHP.ASM

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

     Usage               function _recordend_efw: integer;






                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 20



     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\TURBOPAS\MCCTKIHP.ASM



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

     Usage               function _set_trq(var efw: integer, ticvalue:
                         integer): integer;

     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 $FF.

                         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
                         MCCTKCKP.ASM file.

                         0-$0FFF = 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\TURBOPAS\MCCTKCKP.ASM






                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 21




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

     Usage               procedure _set_trq_time(trqhandle, ticvalue:
                         integer);

     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         \PTK\TURBOPAS\MCCTKCKP.ASM


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

     Usage               procedure _smpte_efw(var efw: integer; smpte_fid:
                         arraay[0..3] of byte);

     Related functions   coproc_slih, _strk_end_efw.

     Description         This procedure returns the current value of the SMPTE
                         frame message EFW in the efw variable.  If the EFW is
                         set, it is cleared and the last received SMPTE frame
                         address is returned in the smpte_fid variable.  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      var efw
                              0 = EFW not set, no SMPTE frame address
                              returned.
                              1 = EFW set, last SMPTE frame address returned.

     Source file         \PTK\TURBOPAS\MCCTKIHP.ASM


-----------------------------------------------------------------------------
_spp_efw
-----------------------------------------------------------------------------







                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 22


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

     Usage               procedure _spp_efw(var efw, spp: integer);

     Related functions   coproc_slih.

     Description         This procedure returns the current value of the Song
                         Position Pointer EFW in the efw variable.  If the EFW
                         is set, it is cleared and the value of the SPP is
                         returned in the spp variable.  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      var efw
                              0 = EFW not set, no SPP value returned.
                              1 = EFW set, SPP value returned.

     Source file         \PTK\TURBOPAS\MCCTKIHP.ASM


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

     Usage               function _strk_end_efw: integer;

     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\TURBOPAS\MCCTKIHP.ASM


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

     Usage               function _track_efw(track_number: integer): integer;

     Related functions   coproc_slih.







                       Turbo Pascal 4.0 and 5.0 ToolKit                Page 23


     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\TURBOPAS\MCCTKIHP.ASM













































