====== ON-GOSUB ======
/* Remove the comments after creating content for each section.*/

Flow control statement that selects a subroutine to jump to according to the value of a variable or numeric expression

/*
  For the lines below, just create links, separated by commas, to other pages of the BASICs section,
  like [[:basics:basicTagName]].
  
  "Implemented by" should mention BASICs which implement the keyword like described, in a more usual and standard way.
  
  "With variations" should point to BASICs where this keyword is used a bit differently.
  
  "Also written as" should list alternative spellings and abbreviations this keyword has. No need to
  refer to a BASIC, there is a section for that later.
*/

**Implemented by:** [[:basics:decbasic:]], [[:basics:Applesoft:]], [[:basics:TI994:]], [[:basics:CBM:]], [[:basics:Atari:]], [[:basics:msatari:]], [[:basics:trs80:]], [[:basics:trscolor:]], [[:basics:trscolor:colormc]], [[:basics:GWBASIC:]], [[:basics:MSX:]], [[:basics:bwbasic:]], [[:basics:bwbasic:bw32]], [[:basics:ABasiC:]], [[:basics:FreeBASIC:]], [[:basics:Gambas:]], [[:basics:ugBASIC:]]

**With variations:** 

**Also written as: **
  * ON-GOS ([[:basics:trs80:|TRS-80 Level I BASIC]])


===== Usage =====
/* For inline examples of syntax, write the keyword between '' and '' (two single quotes) */

ON-GOSUB is a "syntactic sugar" found in many BASICs that can replace a number of [[IF]]-[[THEN]] statements at once, making it specially useful for the so common option menus in character-mode interfaces.

After the [[ON]] particle, there must be a numeric variable or formula that may evaluate 1, 2, 3 and so forth. Then comes the [[GOSUB]] keyword followed by multiple, comma-separated line numbers or labels corresponding to the entry point of different subroutines where the program flow will jump to, according to the value.

<code zxbasic>
10 INPUT "PRESS 1 FOR THE MONEY, 2 FOR THE SHOW, 3 TO GET READY"; V
20 ON V GOSUB 300, 600, 1000
</code>

When each subroutine finds it [[RETURN]] statement, program flow is resumed at the statement after the one with ON-GOSUB.

In most BASICs, there will be no jump if the variable or expression evaluates to 0 or to a value greater than the number of subroutine identifiers in the list. A negative value will cause a runtime error in some implementations.


==== Variations ====

Not all of the old BASICs documentation is assertive on what happens when the variable or expression evaluates to 0.

Information is also scarce about negative values:
  * No problem for [[:basics:gwbasic:|GW-BASIC]] and [[:basics:qb:|QBasic/QuickBASIC]]
  * Runtime error for [[:basics:applesoft:|Applesoft]], [[:basics:cbm:|Commodore BASIC V2]] and [[:basics:trs80:level2|TRS-80 Level II BASIC]] 

Instead of just flowing to the next program line if the value exceeds the number of subroutines, an error will happen on [[:basics:decplus:|DEC BASIC-PLUS]].

The value of the variable/expression usually may be a fractional number that will be forced into an integer value. If you don't do it explicitely, you can have some surprises within the subroutine list:

  * The //[[:basics:ABasiC:|Amiga ABasiC]] Reference Manual// just says it //"rounds the value"//, without telling how exactly
  * Reference guides say that the fractional portion will be simply discarded, round-down in [[FIX]]-style, for [[:basics:msx:|MSX BASIC]], [[:basics:decplus:|DEC BASIC-PLUS]] and [[:basics:cbm:|Commodore BASIC V2]].
  * [[:basics:trs80:level2|TRS-80 Level II BASIC]] rounds the value down in [[INT]] style, which for positive numbers has the same effect of cutting off the fractional part.
  * The //[[:basics:atari:|Atari BASIC]] Rev.C Reference Manual// says the value is //"rounded to the nearest positive integer"//.


8-bit BASICs usually had a limit of 255 for the evaluated value, and a higher value would cause a runtime error. Anyway the user would probably be unable to enter 255 subroutine line numbers after GOSUB as it would exceed the maximum line length. In Microsoft's [[:basics:gwbasic:|GW-BASIC]] and [[:basics:qb:|QBasic/QuickBASIC]], the accepted value ranges from -32768 to 32767. 

/*
===== Examples =====

  Below is an example of a code block, using GeSHi syntax highlighting for //gwbasic//. Other styles of interest might be
  //basic4gl//, //blitzbasic//, //freebasic//, //gambas//, //locobasic//, //purebasic//, //qbasic//, //sdlbasic//,
  //thinbasic//, //vb//, //vbnet//, //xbasic// or //zxbasic//. 

  <code gwbasic>
  10 PRINT "HELLO"
  </code>
*/



===== Comments =====
/* Origin of the keyword, opinions, history... */


===== Related keywords =====
/* Keywords that are often or always used along this one */
  * [[RETURN]]
  * [[ON-GOTO]]
  * [[ON]]

===== Similar keywords =====
/* Keywords with the same or similar functionality found in other versions of BASIC */
  * [[SELECT CASE]]
  * [[IF]]

===== In other languages... =====
/* For parallels and comparisons with other modern-day languages */
ON-GOSUB is somewhat related to the //switch...case// structures of C and derived languages such as PHP and Java.

===== References =====
/* If you used the ((citation)) syntax elsewhere in the text, they will appear under this section. But you can write some recommendations of books, magazines, etc */

/*
  ===== TAGS =====
  Please use the syntax below for adding tags to this page, separated by spaces (use quotes for tags with spaces).
  The most important tags to be used are, separated by groups:
    - Statements | Commands | SpecialVariables | Operators
  
  {{tag>tagName}}
*/
{{tag>Statements "Program Flow"}}