156 lines
10 KiB
HTML
156 lines
10 KiB
HTML
|
<?xml version="1.0" encoding="utf-8"?>
|
|||
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|||
|
|
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="6" MadCap:lastHeight="94" MadCap:lastWidth="853" MadCap:disableMasterStylesheet="true" MadCap:tocPath="" MadCap:InPreviewMode="false" MadCap:PreloadImages="false" MadCap:RuntimeFileType="Topic" MadCap:TargetType="WebHelp" lang="en-us" xml:lang="en-us" MadCap:PathToHelpSystem="../../../" MadCap:HelpSystemFileName="Default.xml" MadCap:SearchType="Stem">
|
|||
|
|
<head><title>GOSUB</title>
|
|||
|
|
<link href="../../SkinSupport/MadCap.css" rel="stylesheet" />
|
|||
|
|
<link href="../../Resources/Stylesheets/BSE_Help.css" rel="stylesheet" />
|
|||
|
|
<script src="../../SkinSupport/MadCapAll.js" type="text/javascript">
|
|||
|
|
</script>
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<h1 class="code">GOSUB</h1>
|
|||
|
|
<div class="ImagePlusCaption">
|
|||
|
|
<div class="Col2">
|
|||
|
|
<p>
|
|||
|
|
<img src="../../graphics/pgm_icon1.gif" border="0" alt="BS1 icon" title="BS1 icon" />
|
|||
|
|
<img src="../../graphics/pgm_icon2.gif" border="0" alt="BS2 icon" title="BS2 icon" />
|
|||
|
|
<img src="../../graphics/pgm_icon2e.gif" border="0" alt="BS2e icon" title="BS2e icon" />
|
|||
|
|
<img src="../../graphics/pgm_icon2sx.gif" border="0" alt="BS2sx icon" title="BS2sx icon" />
|
|||
|
|
<img src="../../graphics/pgm_icon2p.gif" border="0" alt="BS2p icon" title="BS2p icon" />
|
|||
|
|
<img src="../../graphics/pgm_icon2pe.gif" border="0" alt="BS2pe icon" title="BS2pe icon" />
|
|||
|
|
<img src="../../graphics/pgm_icon2px.gif" border="0" alt="BS2px icon" title="BS2px icon" />
|
|||
|
|
</p>
|
|||
|
|
</div>
|
|||
|
|
<p style="text-align: right;"><a href="../ExampleTopics/GosubEx.htm" target="" title="" alt="" class="MCXref_0">GOSUB Examples</a>
|
|||
|
|
</p>
|
|||
|
|
<p> </p>
|
|||
|
|
</div>
|
|||
|
|
<p class="clear"> </p>
|
|||
|
|
<p> </p>
|
|||
|
|
<p class="PlainText">Syntax: <span class="keyword_in_text">GOSUB</span> <![CDATA[ ]]><i>Address</i></p>
|
|||
|
|
<h2>Function</h2>
|
|||
|
|
<p class="PlainText">Store the address of the next instruction after <span class="keyword_in_text">GOSUB</span>, then go to the point
|
|||
|
|
in the program specified by <i>Address</i>; with the intention of returning to the
|
|||
|
|
stored address.
|
|||
|
|
|
|||
|
|
</p>
|
|||
|
|
<ul>
|
|||
|
|
<li value="1"><b><i>Address</i></b> is a label that specifies where to go.</li>
|
|||
|
|
</ul>
|
|||
|
|
<h2>Quick Facts</h2>
|
|||
|
|
<table width="100%" cellpadding="4" cellspacing="0" border="1">
|
|||
|
|
<tr>
|
|||
|
|
<td width="24%" align="center" bgcolor="#CFCFCF"> </td>
|
|||
|
|
<td width="38%" align="center" bgcolor="#CFCFCF">BS1*</td>
|
|||
|
|
<td width="38%" align="center" bgcolor="#CFCFCF">BS2 Family</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td align="center" bgcolor="#CFCFCF">Maximum GOSUBs per program</td>
|
|||
|
|
<td align="center">16</td>
|
|||
|
|
<td align="center">255</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td align="center" bgcolor="#CFCFCF">Maximum nested GOSUBs</td>
|
|||
|
|
<td align="center">4</td>
|
|||
|
|
<td align="center">4</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td align="center" bgcolor="#CFCFCF">Related Commands</td>
|
|||
|
|
<td align="center"><a href="GOTO.htm" target="" title="" alt="" class="MCXref_0">GOTO</a>
|
|||
|
|
</td>
|
|||
|
|
<td align="center"><a href="ON_GOSUB.htm" target="" title="" alt="" class="MCXref_0">ON...GOSUB</a>, <a href="GOTO.htm" target="" title="" alt="" class="MCXref_0">GOTO</a></td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
<p> </p>
|
|||
|
|
<P>*<img src="../../graphics/bs1note.gif" style="vertical-align: super;" /> Note: Using <span class="keyword_in_text">GOSUB</span> on the BS1 requires variables B12 and B13 (W6) making them unavailable for general program use.</P>
|
|||
|
|
<h2>Explanation</h2>
|
|||
|
|
<p class="PlainText"><span class="keyword_in_text">GOSUB</span> is a close relative of <span class="keyword_in_text">GOTO</span>, in fact, its name means, "GO
|
|||
|
|
to a SUBroutine". When a PBASIC program reaches a <span class="keyword_in_text">GOSUB</span>, the program
|
|||
|
|
executes the code beginning at the specified address label. Unlike <span class="keyword_in_text">GOTO</span>,
|
|||
|
|
<span class="keyword_in_text">GOSUB</span> also stores the address of the instruction immediately following
|
|||
|
|
itself. When the program encounters a <span class="keyword_in_text">RETURN</span> command, it interprets it
|
|||
|
|
to mean, "go to the instruction that follows the most recent <span class="keyword_in_text">GOSUB</span>." In
|
|||
|
|
other words, a <span class="keyword_in_text">GOSUB</span> makes the BASIC Stamp do a similar operation as
|
|||
|
|
you do when you see a table or figure reference in this manual; 1) you
|
|||
|
|
remember where you are, 2) you go to the table or figure and read the
|
|||
|
|
information there, and 3) when you've reached the end of it, you "return"
|
|||
|
|
to the place you were reading originally.</p>
|
|||
|
|
<h3>GOSUB Can Save EEPROM (Program) Space</h3>
|
|||
|
|
<p class="PlainText"><span class="keyword_in_text">GOSUB</span> is mainly used to execute the same piece of code from multiple
|
|||
|
|
locations. If you have, for example, a block of three lines of code that need
|
|||
|
|
to be run from 10 different locations in your entire program you could
|
|||
|
|
simple copy and paste those three lines to each of those 10 locations. This
|
|||
|
|
would amount to a total of 30 lines of repetitive code (and extra space
|
|||
|
|
wasted in the program memory). A better solution is to place those three
|
|||
|
|
lines in a separate routine, complete with it's own label and followed by a
|
|||
|
|
<span class="keyword_in_text">RETURN</span> command, then just use a <span class="keyword_in_text">GOSUB</span> command at each of the 10
|
|||
|
|
locations to access it. This technique can save a lot of program space.</p>
|
|||
|
|
<p class="PlainText">Try the example below:
|
|||
|
|
|
|||
|
|
</p><pre class="BScode" xml:space="preserve">
|
|||
|
|
Main:
|
|||
|
|
GOSUB Hello
|
|||
|
|
DEBUG "How are you?", CR
|
|||
|
|
END
|
|||
|
|
|
|||
|
|
Hello:
|
|||
|
|
DEBUG "Hello my friend.", CR
|
|||
|
|
RETURN
|
|||
|
|
</pre>
|
|||
|
|
<p class="PlainText">The above code will start out by executing a <span class="keyword_in_text">GOSUB </span>to the section of code beginning with the label Hello. It will print "Hello my friend." on the screen then <span class="keyword_in_text">RETURN </span>to the line after the <span class="keyword_in_text">GOSUB</span>...which prints "How are you?" and <span class="keyword_in_text">END</span>s.</p>
|
|||
|
|
<h3>Watch Out For Subroutines That Your Program Can "Fall Into"</h3>
|
|||
|
|
<p class="PlainText">There's another interesting lesson here; what would happen if we removed
|
|||
|
|
the <span class="keyword_in_text">END</span> command from this example? Since the BASIC Stamp reads the
|
|||
|
|
code from left to right / top to bottom (like the English language) once it
|
|||
|
|
had returned to and run the "How are you?" line, it would naturally "fall
|
|||
|
|
into" the Hello routine again. Additionally, at the end of the Hello routine,
|
|||
|
|
it would see the <span class="keyword_in_text">RETURN</span> again (although it didn't <span class="keyword_in_text">GOSUB</span> to that
|
|||
|
|
routine this time) and because there wasn't a previous place to return to, the
|
|||
|
|
BASIC Stamp will start the entire program over again. This would cause
|
|||
|
|
an endless loop. The important thing to remember here is to always make
|
|||
|
|
sure your program doesn't allow itself to "fall into" a subroutine.</p>
|
|||
|
|
<p>*<img src="../../graphics/bs1note.gif" style="vertical-align: super;"></img> Note: On the BS1, a <span class="keyword_in_text">RETURN</span> without a <span class="keyword_in_text">GOSUB</span> will return
|
|||
|
|
the program to the last <span class="keyword_in_text">GOSUB</span> (or will end the program if no <span class="keyword_in_text">GOSUB</span>was executed).</p>
|
|||
|
|
<h3>GOSUB Limitations</h3>
|
|||
|
|
<p class="PlainText">Only a limited number of <span class="keyword_in_text">GOSUB</span>s are allowed per program (as shown in above),
|
|||
|
|
and they may be nested only four levels deep. In other words, the subroutine that's
|
|||
|
|
the destination of a <span class="keyword_in_text">GOSUB</span> can contain a <span class="keyword_in_text">GOSUB</span> to another subroutine,
|
|||
|
|
and so on, to a maximum depth (total number of <span class="keyword_in_text">GOSUB</span>s before the first
|
|||
|
|
<span class="keyword_in_text">RETURN</span>) of four. Any deeper, and the program will "forget" its way back to
|
|||
|
|
the starting point (the instruction following the very first <span class="keyword_in_text">GOSUB</span>).</p>
|
|||
|
|
<p class="PlainText">When <span class="keyword_in_text">GOSUB</span>s are nested, each <span class="keyword_in_text">RETURN</span> takes the program back to the
|
|||
|
|
instruction after the most-recent <span class="keyword_in_text">GOSUB</span>. As is mentioned above, if the
|
|||
|
|
BASIC Stamp encounters a <span class="keyword_in_text">RETURN</span> without a previous <span class="keyword_in_text">GOSUB</span>, the
|
|||
|
|
entire program starts over from the beginning. Take care to avoid these
|
|||
|
|
phenomena.</p>
|
|||
|
|
<div class="Col2">
|
|||
|
|
<div class="MasterFoot">
|
|||
|
|
<p MadCap:conditions="BSEconditions.BSEWebHelp (Primary)-INCLUDE"><a href="../../HomeTopics/HomePage.htm">Go to Welcome page</a>
|
|||
|
|
</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="Col2">
|
|||
|
|
<div class="MasterFoot">
|
|||
|
|
<p style="text-align: right;"><span class="ContactInfoProjectName">BASIC Stamp Help</span> <![CDATA[ ]]><span class="ContactInfoVersion#">Version 2.5.4</span> <![CDATA[ ]]></p>
|
|||
|
|
<p style="text-align: right;">Copyright © <span class="ContactInfoCompanyName">Parallax Inc.</span></p>
|
|||
|
|
<p style="text-align: right;"><span class="SystemShortDate">8/8/2012</span>
|
|||
|
|
</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">/* <![CDATA[ */
|
|||
|
|
|
|||
|
|
var _gaq = _gaq || [];
|
|||
|
|
_gaq.push(['_setAccount', 'UA-285614-1']);
|
|||
|
|
_gaq.push(['_trackPageview']);
|
|||
|
|
|
|||
|
|
(function() {
|
|||
|
|
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
|
|||
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
|||
|
|
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
|
|||
|
|
})();
|
|||
|
|
|
|||
|
|
/* ]]> */</script>
|
|||
|
|
<script type="text/javascript" src="../../SkinSupport/MadCapBodyEnd.js">
|
|||
|
|
</script>
|
|||
|
|
</body>
|
|||
|
|
</html>
|