
















                       Music Quest Programmer's ToolKit



                       Quick Basic 4.0 and 4.5 Interface



                                  Version 4.2












                              September 5, 1991




                   Copyright 1988, 1990 by Music Quest, Inc.

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


























                               Table of Contents



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

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

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

ToolKit Functions - Description . . . . . . . . . . . . . . . . . . . . .    8
     acknefw  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    8
     addtrqtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    8
     clearefw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    9
     clockefw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    9
     conductorefw . . . . . . . . . . . . . . . . . . . . . . . . . . . .    9
     cuepointefw  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   10
     endtrq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   10
     mccclose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   11
     mcccommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   11
     mccflush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   12
     mccget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   12
     mccirq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   13
     mccopen  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   13
     mccput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   14
     mccreset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   14
     mccsetcoprocslih . . . . . . . . . . . . . . . . . . . . . . . . . .   14
     mccsetnoslih . . . . . . . . . . . . . . . . . . . . . . . . . . . .   15
     mccsetreceiveslih  . . . . . . . . . . . . . . . . . . . . . . . . .   15
     mclkinit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   16
     mclkstart  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   16
     mclkstop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   17
     measurendefw . . . . . . . . . . . . . . . . . . . . . . . . . . . .   17
     midiclock  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   17
     playendefw . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   18
     realtimeefw  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   18
     recbytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   19
     recinit  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   19
     recoverflow  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   19
     recordendefw . . . . . . . . . . . . . . . . . . . . . . . . . . . .   20
     settrq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   20
     settrqtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   21
     smpteefw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   21
     sppefw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   22
     strkendefw . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   22
     trackefw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   23













                            Quick Basic 4.0 ToolKit                     Page 3


Introduction

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

     Files
          Describes each of the files that comprise the Quick Basic 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.

If you use the Quick Basic interactive environment, you should review chapters
8 and 9 of the "Learning and Using Microsoft QuickBASIC" manual.  These
chapters explain how to use and maintain Quick Libraries and stand alone
libraries, which are integral to the QB environment.

Files

The following files make up the Quick Basic interface.

\PTK\QBASIC\RUNXMPL.BAT
     A batch file that loads the Quick Basic Editor and runs the TKXMPL
     program.

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

\PTK\QBASIC\TKXMPL.OBJ
     The compiled object code for TKXMPL.BAS.

\PTK\QBASIC\TKXMPL.QLK
\PTK\QBASIC\TKXMPL45.QLK
     This is the LINK control file for the TKXMPL program.  Use it with the
     LINK program to link all of the *.OBJ files together into an executable
     program.  It also shows you which ToolKit files you need to link together
     to form the Quick Basic interface.  Use TKXMPL.QLK with QB 4.0 and
     TKXMPL45.QLK with QB 4.5.

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

\PTK\QBASIC\TKITRACE.BAS
     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\QBASIC\TKITRACE.OBJ
     The compiled object code for TKITRACE.BAS.







                            Quick Basic 4.0 ToolKit                     Page 4


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

\PTK\QBASIC\MCCTKSEQ.OBJ
     The compiled object code for MCCTKSEQ.BAS.

\PTK\QBASIC\MCC.CST
     This file contains definitions (CONST) 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\QBASIC\MCC.INC
     This file contains declarations for all of the SUBs and FUNCTIONs that
     make up the Quick Basic interface.  Whenever you want to use the ToolKit
     functions, you must include this file.

\PTK\QBASIC\MCC40.LNK
\PTK\QBASIC\MCC45.LNK
     This file contains the statements that build the MCCxx.QLB file (use
     MCC40.LNK for QB 4.0 and MCC45.LNK for QB 4.5).  To rebuild the MCCxx.QLB
     file, invoke the linker as follows:

          LINK @MCCxx.LNK

     When building a Quick Library, be sure to use the LINK program that was
     on the Quick Basic diskettes.

\PTK\QBASIC\MCC40.QLB
\PTK\QBASIC\MCC45.QLB
     This file is a Quick Library containing all of the *.OBJ files needed to
     create a program under the Quick Basic environment.  When you start Quick
     Basic, use the /l option to specify this file as a Quick Library to be
     loaded.  The MCC40.QLB file is for QB 4.0 and MCC45.QLB is for QB 4.5.

\PTK\QBASIC\MCC.TLL
     This file contains the library contol statements used to build the
     MCC.LIB file.  To update the MCC.LIB file, invoke the library utility as
     follows:

          LIB @MCC.TLL

\PTK\QBASIC\MCC.LIB
     This file is an object library containing all of the ToolKit *.OBJ files. 
     The QB interactive environment uses this library to build an EXE file.


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

\PTK\ASM\MCCTKFB.OBJ
     The assembled object code for MCCTKF.ASM (Quick Basic language).








                            Quick Basic 4.0 ToolKit                     Page 5


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

\PTK\ASM\MCCTKIHB.OBJ
     The assembled object code for MCCTKIH.ASM (Quick Basic language).

\PTK\ASM\MCCTKCK.ASM
     This file contains the source code for the timer services.  The timer
     services are implemented as an extension to the co-processor mode second
     level interrupt handler (MCCTKIH).  The timer services facilitate using
     the interface's clock.

\PTK\ASM\MCCTKCKB.OBJ
     The assembled object code for MCCTKCK.ASM (Quick Basic language).


ToolKit Functions - Overview

The Quick Basic ToolKit is divided into three distinct groups of functions.


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


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

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

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

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


The Basic Interface (MCCTKF.ASM)

The basic interface services allow you to send commands and data to the
interface, and to receive data from the interface.  The TKXMPL.BAS source file







                            Quick Basic 4.0 ToolKit                     Page 6


illustrates how to use the basic services.  In pseudo code terms, you use the
basic services as follows:

     1.   Call mccopen 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 setslih 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 mccreceive SLIH
          stores each incoming data byte in a circular receive buffer.  You
          retrieve data bytes from the receive buffer through the mccget
          function.  The noslih 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 mcccommand function to send commands to the interface.  Use
          the mccput function to send command operands to the interface.

     4.   Use the mccput and mccget functions to send and receive data. 
          Remember that the mccget function works ONLY when the mccreceive
          SLIH is installed as the current SLIH.

     5.   When the program completes execution, invoke the mccclose service. 
          This service resets the interface to power-on state and removes the
          FLIH.  NEVER use mccopen without mccclose.  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 coprocslih 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






                            Quick Basic 4.0 ToolKit                     Page 7


Words (EFWs).  An EFW is essentially a "mark on the wall" that the coprocslih
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
conductorefw 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 setslih service, specifying
coprocslih as the new SLIH.

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

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


Timer Services (MCCTKCK.ASM)

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

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

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

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

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















                            Quick Basic 4.0 ToolKit                     Page 8


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:

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

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

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

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

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

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

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

     Usage               value%=acknefw

     Related functions   mcccommand

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

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

     Source file         \PTK\ASM\MCCTKF.ASM

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

     Usage               addtrqtime trqhandle%, ticks%

     Related functions   settrq, settrqtime








                            Quick Basic 4.0 ToolKit                     Page 9


     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 settrqtime to establish a new TRQ time
                         value.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKCK.ASM


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

     Usage               clearefw(VARPTR(efw))

     Related functions   settrq

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

     Returned value      None.

     Source file         \PTK\ASM\MCCTKCK.ASM


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

     Usage               value%=clockefw

     Related functions   None.

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

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

     Source file         \PTK\ASM\MCCTKIH.ASM


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






                            Quick Basic 4.0 ToolKit                    Page 10



     Usage               value%=conductorefw

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



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

     Usage               value%=cuepoint_efw

     Related functions   smpte_efw.

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

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

     Source file         \PTK\ASM\MCCTKIH.ASM

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

     Usage               endtrq(trqhandle%)

     Related functions   settrq.

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

     Returned value      None.

     Source file         \PTK\ASM\MCCTKCK.ASM






                            Quick Basic 4.0 ToolKit                    Page 11




-----------------------------------------------------------------------------
mccclose
-----------------------------------------------------------------------------
     Name                mccclose - close basic interface services.

     Usage               mccclose

     Related functions   mccopen.

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

     Returned value      None.

     Source file         \PTK\ASM\MCCTKF.ASM


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

     Usage               value%=mcccommand(cmd%)

     Related functions   mccput, setslih.

     Description         This function sends a command to the interface,
                         according to the protocol for sending commands. 
                         After the command is sent, mcccommand 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 mcccommand is waiting for the acknowledge.

                         Use the mccput 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\ASM\MCCTKF.ASM













                            Quick Basic 4.0 ToolKit                    Page 12


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

     Usage               mccflush

     Related functions   setslih, mccreceive, mccget, mccnoslih.

     Description         This function flushes all queued data bytes from the
                         receive buffer that is managed by the mccreceive
                         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
                         mccnoslih as the current SLIH, whenever you do not
                         want any incoming data.  The mccnoslih routine
                         discards everything that it receives.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKF.ASM


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

     Usage               value%=mccget

     Related functions   mccreceive, setslih.

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

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

     Source file         \PTK\ASM\MCCTKF.ASM


















                            Quick Basic 4.0 ToolKit                    Page 13


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

mccirq
-----------------------------------------------------------------------------
     Name                mccirq - determine IRQ being used by interface.

     Usage               value%=mccirq ioaddr%

     Related functions   mccopen.

     Description         This function determines the interrupt level being
                         used by the interface.  The value ioaddr, specifies
                         the base I/O address of the interface (typically
                         0x330).  It is recommended that you use this function
                         in all programs, because if makes you program immune
                         to the interface's interrupt assignment.

     Returned value      0 = unable to locate 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 interface.

     Source file         \PTK\ASM\MCCTKF.ASM


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

     Usage               value%=mccopen ioaddr%, irqlevel%

     Related functions   mccclose.

     Description         This function initializes the ToolKit services, much
                         like opening a file initializes I/O services for the
                         file.  The value ioaddr, specifies the base I/O
                         address of the interface (typically 0x330), while the
                         value  irqlevel specifies the interrupt level
                         assigned to the interface.  When mccopen 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.









                            Quick Basic 4.0 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         \PTK\ASM\MCCTKF.ASM


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

     Usage               mccput(dbyte%)

     Related functions   mccget, mcccommand.

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

     Returned value      None.

     Source file         \PTK\ASM\MCCTKF.ASM


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

     Usage               mccreset

     Related functions   None.

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

     Returned value      None.

     Source file         \PTK\ASM\MCCTKF.ASM


-----------------------------------------------------------------------------
mccsetcoprocslih
-----------------------------------------------------------------------------







                            Quick Basic 4.0 ToolKit                    Page 15


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

     Usage               mccsetcoprocslih

     Related functions   mccsetreceiveslih, mccsetnoslih.

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

     Returned value      None.

     Source file         \PTK\ASM\MCCTKFB.ASM


-----------------------------------------------------------------------------
mccsetnoslih
-----------------------------------------------------------------------------
     Name                mccset -noslih - install dummy second level interrupt
                         handler.

     Usage               mccsetnoslih

     Related functions   setslih.

     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.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKF.ASM


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

     Usage               mccsetreceiveslih

     Related functions   setslih, noslih, mccget, mccflush.

     Description         This function installs the basic SLIH (mccreceive). 
                         When mccreceive is installed, it queues every
                         incoming data byte in a circular receive buffer.  Use
                         the mccget function to retrieve the data bytes from
                         the receive buffer.  Use the mcflush routine to
                         discard all of the current contents of the receive
                         buffer.

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






                            Quick Basic 4.0 ToolKit                    Page 16



     Returned value      None.

     Source file         \PTK\ASM\MCCTKF.ASM

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

     Usage               mclkinit(ticvalue%);

     Related functions   mclkstart, mclkstop.

     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:

                              mclkinit(4);

                         correctly initializes the timer services. 

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

     Returned value      None.

     Source file         \PTK\ASM\MCCTKCK.ASM


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

     Usage               mclkstart

     Related functions   mclkinit, mclkstop.

     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 mclkstop function to stop the flow of clock
                         to PC messages, effectively suspending timer service
                         operation.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKCK.ASM







                            Quick Basic 4.0 ToolKit                    Page 17



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

     Usage               mclkstop

     Related functions   mclkinit, mclkstart.

     Description         This function is the complement to the mclkstart
                         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\ASM\MCCTKCK.ASM


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

     Usage               value%=measurendefw

     Related functions   None.

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

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

     Source file         \PTK\ASM\MCCTKIH.ASM


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

     Usage               value%=midiclock

     Related functions   mclkinit, mclkstart, mclkstop.

     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,
                         midiclock always returns the number of interface
                         clock ticks that have been counted since the last
                         call.






                            Quick Basic 4.0 ToolKit                    Page 18



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

     Returned value      The current value of the running tick counter.

     Source file         \PTK\ASM\MCCTKCK.ASM


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

     Usage               value%=playendefw

     Related functions   coprocslih.

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

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

     Source file         \PTK\ASM\MCCTKIH.ASM


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

     Usage               vallue%=realtimeefw

     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.
                         &hFA = EFW set by MIDI start.
                         &hFB = EFW set by MIDI continue.
                         &hFC = EFW set by MIDI stop.

     Source file         \PTK\ASM\MCCTKIH.ASM







                            Quick Basic 4.0 ToolKit                    Page 19



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

     Usage               value%=recbytes

     Related functions   recinit, coprocslih.

     Description         The recinit function passes a recording buffer to the
                         co-processor SLIH.  The recbytes function tells you
                         how many bytes have been used.  Typically, you use
                         the recbytes 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\ASM\MCCTKIH.ASM


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

     Usage               recinit VARSEG(buffer), VARPTR(buffer), buffsize%

     Related functions   recbytes, recoverflow, coprocslih.

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

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

     Returned value      None.

     Source file         \PTK\ASM\MCCTKIH.ASM

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

     Usage               value%=recoverflow

     Related functions   recinit, coprocslih.






                            Quick Basic 4.0 ToolKit                    Page 20



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

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

     Usage               value%=recordendefw

     Related functions   None.

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

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

     Source file         \PTK\ASM\MCCTKIH.ASM



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

     Usage               trqhandle%=settrq VARPTR(efw), ticvalue%);

     Related functions   endtrq, settrqtime, addtrqtime, clearefw.

     Description         The settrq 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






                            Quick Basic 4.0 ToolKit                    Page 21


                         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 settrqtime and addtrqtime functions can be used
                         to establish a new tick count, thus allowing the TRQ
                         to be used repetitively.

                         Use the clearefw function to safely reset the EFW.

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

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

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

     Source file         \PTK\ASM\MCCTKCK.ASM


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

     Usage               settrqtime trqhandle%, ticvalue%

     Related functions   settrq, addtrqtime.

     Description         The settrqtime function sets up a new timer value for
                         a TRQ previously created by the settrq 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 settrq
                         function.

     Returned value      None.

     Source file         \PTK\ASM\MCCTKCK.ASM


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

     Usage               DIM smptefid string*4
                         smpteefw efw%, VARPTR(smptefid)







                            Quick Basic 4.0 ToolKit                    Page 22


     Related functions   coproc_slih, strk_end_efw.

     Description         This function 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 smptefid.  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      efw%
                              0 = EFW not set, no SMPTE frame address
                              returned.
                              1 = EFW set, last SMPTE frame address returned.

     Source file         \PTK\ASM\MCCTKIH.ASM


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

     Usage               spp_efw efw%, spp%

     Related functions   coproc_slih.

     Description         This function 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      efw%
                              0 = EFW not set, no SPP value returned.
                              1 = EFW set, SPP value returned.

     Source file         \PTK\ASM\MCCTKIH.ASM


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

     Usage               value%=strkendefw

     Related functions   coproc_slih, smpteefw.

     Description         This function returns the current value of the SMPTE
                         Track End EFW.  If the EFW is set, it is cleared. 






                            Quick Basic 4.0 ToolKit                    Page 23


                         The SMPTE Track End EFW is set whenever the co-
                         processor slih receives an End of SMPTE Track message
                         from the MQX-32.  This message is sent when the MQX-
                         32 detects the end of SMPTE tape data. 

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

     Source file         \PTK\ASM\MCCTKIH.ASM


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

     Usage               value%=trackefw(tracknumber%)

     Related functions   coprocslih.

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

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

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

     Source file         \PTK\ASM\MCCTKIH.ASM
























