Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

  ◄Syntax►  ◄Details►  ◄Example►                 ◄Contents►  ◄Index►  ◄Back►
──────────────────────────────────────────────────────────────────────────────
ON PLAY is an event-trapping statement that specifies a routine to branch
to when there are fewer than queuelimit% notes in the background-music
queue.
 
ON PLAY(queuelimit%) GOSUB {linenumber | linelabel}
    ■ linenumber or    A linenumber value of 0 disables event trapping and
      linelabel        does not specify line 0 as the start of the
                       routine.
 
Usage Notes
    ■ A play-event trap occurs only when music is playing in the
      background. Play-event traps do not occur when music is running in
      the foreground.
    ■ A play-event trap does not occur if the background-music queue has
      already gone from having queuelimit% notes to queuelimit% - 1 notes
      when a PLAY ON is executed.
    ■ If queuelimit% is a large number, event traps may occur often enough
      to slow down the program.
    ■ The ON PLAY statement specifies only the start of an event-trapping
      routine. The ◄PLAY Statements► determine whether the routine is
      called and how events are handled when trapping is off:
 
        PLAY ON      Enables event trapping. Event trapping occurs only
                     after a PLAY ON statement is executed.
        PLAY OFF     Disables event trapping. Even if an event takes place,
                     it is not remembered.
        PLAY STOP    Suspends event trapping. Any events that occur are
                     remembered and are trapped as soon as a PLAY ON
                     statement is executed.
 
    ■ If your program contains event-handling statements and you are
      compiling from the BC command line, use the BC /W or /V option.
      (The /W option checks for events at every label or line number; the
      /V option checks at every statement.) If you do not use these
      options and your program contains event traps, BASIC generates the
      error message, "ON event without /V or /W on command line."
    ■ The RETURN linenumber or RETURN linelabel forms of RETURN can be
      used to return to a specific line from the trapping routine. Use
      this type of return with care, however, because any other GOSUB,
      WHILE, or FOR statements active at the time of the trap remain
      active. BASIC may generate error messages such as "NEXT without
      FOR." In addition, if an event occurs in a procedure, a RETURN
      linenumber or RETURN linelabel statement cannot get back into the
      procedure because the line number or label must be in the
      module-level code.