Initial commit after migrating repo and assuring the product launches
This commit is contained in:
156
help/BasicStampHelp/Content/LanguageTopics/Commands/GOSUB.htm
Normal file
156
help/BasicStampHelp/Content/LanguageTopics/Commands/GOSUB.htm
Normal file
@ -0,0 +1,156 @@
|
||||
<?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>
|
||||
Reference in New Issue
Block a user