home *** CD-ROM | disk | FTP | other *** search
/ Sound Sensations! / sound_sensations.iso / demos / promidi7 / sda_user.arc / SDA_USER.DOC < prev   
Text File  |  1986-12-16  |  6KB  |  177 lines
  1.         Software Interface to the Promidi Studio System, SDA--200.
  2.  
  3.  
  4.  
  5.                     Systems Design Associates, Inc.
  6.                      928 W. University Suite 660
  7.                          Denton, Texas  76201
  8.  
  9.  
  10.  
  11. Revision: 1.0
  12. Release Date:     12-15-86
  13. Software: C11 and above.
  14.  
  15.  
  16.  
  17.  
  18. This document is intended to describe the Promidi Software Userì
  19. Interface as it pertains to memory resident software.  Both thisì
  20. document and the accompanying source file of IBM assembly languageì
  21. subroutines, SDA_USER.ASM, are in the public domain.  This growingì
  22. collection of subroutines is intended to provide designers of memoryì
  23. resident software access into a running Promidi system.  Through theseì
  24. subroutines Promidi can be used to provide services much like anì
  25. operating system, ranging in complexity from simple Midi Get and Putì
  26. Byte routines, to complete Record and Playback functions.
  27.  
  28. This document is intended to provide specific information to designersì
  29. already familiar with what is known as 'IBM-PC Terminate-and-Stay-Resident' 
  30. software design.
  31.  
  32.  
  33.  
  34. Memory Resident Software Requirements.
  35.  
  36.   PC-DOS (MS-DOS) 2.0 or later is required.
  37.  
  38.   384 K. Bytes plus the memory necessary for the resident software is
  39.   required.
  40.  
  41.   The software should be installed before Promidi is run.
  42.  
  43.   The software should get control by intercepting INT 16 (The keyboard
  44.   I/O call) and looking for an ALT key (Promidi does not use ALT keys),
  45.   but only if AH is 0, that is, Promidi is actually reading (not
  46.   testing for) a keystroke.
  47.  
  48.   Promidi does not use graphics modes in any of its screens, therefore,
  49.   saving the screens is relatively straightforward.  In the future, SDA
  50.   intends to provide a general-purpose 'screen redraw' subroutine to be
  51.   used at the end of the user interrupt.
  52.  
  53.   The software should return the ALT key to Promidi at the end of the
  54.   interrupt.  If this is not done, upon returning to Promidi, the user
  55.   will have to hit an "extra" keystroke.
  56.  
  57.   Calls into Promidi require only 40 bytes of user stack space
  58.   (maximum).  Promidi's stacks are used for all operations.
  59.  
  60.  
  61. Using The Subroutines in 'SDA_USER.ASM'.
  62.  
  63. These subroutines, while provided in IBM MASM assembler format, areì
  64. callable as C Functions when linked Microsoft C (versions 3.0 andì
  65. greater) modules.  Whether called from C or assembler language, they areì
  66. FAR routines.  If NEAR calls are desired, or if for instance theì
  67. designer wishes to pass and return parameters differently, the source inì
  68. SDA_USER.ASM may be modified accordingly.
  69.  
  70.  
  71.  
  72. Saving Promidi's Data Segment (DS register).
  73.  
  74. Upon each entrance to the memory resident software (through INT 16),ì
  75. when saving Promidi's context, the contents of Promidi's DS registerì
  76. must be saved in '_SDA_DSEG' (public in SDA_USER.ASM).
  77.  
  78.  
  79.  
  80. Checking for The Midicard Interface.
  81.  
  82. Upon each entrance to the memory resident software (through INT 16), theì
  83. subroutine '_CHECK4_SDA' must be called SUCCESSFULLY.  This routineì
  84. performs two functions:
  85.  
  86.   1. It test for and locates a running SDA Midicard Interface.
  87.   2. It run-time binds the memory resident software to Promidi.
  88.  
  89. If this routine does not complete successfully (see subroutine header inì
  90. 'SDA_USER.ASM'), no other Promidi subroutines should be called.
  91.  
  92.  
  93.  
  94. CURRENT LIST OF USER SUBROUTINES.
  95.  
  96. Output.
  97.  
  98.   _SDA_PUTB  -  Send a byte (of a complete Midi message) out Midi Out.
  99.  
  100.  
  101.  
  102. Input.
  103.  
  104.   _SDA_RECON  -  Go into record mode.
  105.  
  106.     This routine must be called before any input can be received via
  107.     the Midicard Interface.  It has three functions:
  108.  
  109.       1. It check to see if Promidi is currently recording.  If so no
  110.          user recording can be done.
  111.  
  112.       2. It allocates a record buffer within Promidi (the number of
  113.          bytes are returned from the call).  This buffer will usually
  114.          be about 40K bytes.
  115.  
  116.       3. It tells the Midicard to start sending data to Promidi.
  117.  
  118.  
  119.  
  120.  
  121.   _SDA_RECOFF  -  Leave record mode.
  122.  
  123.     This routine must be called (if _SDA_RECON was called) before the
  124.     memory resident sotware terminates (returns from INT16).
  125.  
  126.     ** Failure to do so will result in the loss of the record buffer. **
  127.  
  128.  
  129.   _SDA_GETB  -  Get a byte of a complete Midi message from the record
  130.                 buffer.
  131.  
  132.  
  133.  
  134.  
  135. General.
  136.  
  137.   _SDA_EXEC  -  Runs other Promidi Tasks.
  138.  
  139.     If the memory resident software needs to run while Promidi is
  140.     recording and/or playing, frequent calls to _SDA_EXEC are necessary
  141.     to keep the record playback process 'alive'.  A call every 15 or 20
  142.     milliseconds is usually sufficient to keep the Midicard supplied
  143.     with data (playback).
  144.  
  145.  
  146.  
  147.  
  148. Notes on The Environment.
  149.  
  150. Promidi only reads keyboard characters (INT 16, AH=0) from one of itsì
  151. tasks.  The memory resident software, even though it accessed as anì
  152. interrupt, becomes an extension of that task when it uses Promidiì
  153. services via the SDA_USER subroutines.  That task does not do disk I/O. ì
  154. To keep disk I/O active during Promidi's record or playback, calls toì
  155. _SDA_EXEC are required.
  156.  
  157.  
  158.  
  159.  
  160. The source file 'SDA_USER.ASM' is provided free of charge by Systems 
  161. Design Associates, Inc.  SDA does not in any way warranty this software 
  162. nor is it liable for any damages resulting from its use.
  163.  
  164.  
  165.  
  166.  
  167. Revision: 1.0
  168. Date:     12-01-86
  169. 
  170.      12-15-86
  171. Software: C11 and above.
  172.  
  173.  
  174.  
  175.  
  176. This document is intended to describe the Promidi Software Userì
  177. Interface as