PLAY Function
 ----------------------------------------------------------------------------


 Action

 Returns the number of notes currently in the background-music queue.


 Syntax


  PLAY ( n)

 Remarks


 The argument  n is a dummy argument and can be any numeric value.

  PLAY( n) will return 0 when music is running in the foreground.

 The  PLAY function is not available for OS-2 protected mode.


 See Also

  ON  event,  PLAY Statements (Event Trapping),  PLAY Statement (Music)


 Example

 The following example plays continuous music by calling an event-handling
 routine when the background music buffer goes from three to two notes.

 CLS
 ' Call routine Replay when the music buffer goes
  ' from 3 to 2 notes.
 ON PLAY(3) GOSUB Replay
 ' Turn on event trapping for PLAY.
 PLAY ON
 ' Define a string containing the melody.
 FElise$ = "o3 L8 E D+ E D+ E o2 B o3 D C L2 o2 A"
 PLAY "MB X" + VARPTR$(FElise$)
 ' Suspend event trapping until next PLAY ON but remember
  ' events that occur while event trapping is disabled.
 PLAY STOP
 ' Introduce a variable-length delay.
 LOCATE 23, 1. PRINT "Press any key to continue."
 DO
 LOOP WHILE INKEY$ = ""

 ' Re-enable play-event trapping, remembering that a play event

  ' has occurred.
 PLAY ON
 LOCATE 23, 1. PRINT "Press any key to stop.    "
 ' Loop until a key is pressed.
 DO
     GOSUB BackGround
 LOOP WHILE INKEY$ = ""
 ' Disable play-event processing.
 PLAY OFF
 ' Count down to 0 notes in the queue.
 DO
     GOSUB BackGround
 LOOP UNTIL NoteCount = 0
 END

 ' Play event-handling routine.
 Replay.
     ' Increment and print a counter each time.
     Count% = Count% + 1
     LOCATE 3, 1. PRINT "Replay routine called"; Count%; "time(s)";
     ' Play it again to fill the buffer.
     PLAY "MB X" + VARPTR$(FElise$)
 RETURN

 ' Background music queue reporting routine.
 BackGround.
     ' Get a note count.
     NoteCount = PLAY(0)
     LOCATE 1, 1
     PRINT "Background queue notes remaining --> "; NoteCount
     ' Loop until Notecount changes or equals 0.
     DO
     LOOP UNTIL NoteCount <> PLAY(0) OR NoteCount = 0
 RETURN