Sub (explanatory): Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
(Created page with "A '''SUB''' procedure is a procedure within a program that can calculate and return multiple parameter values just like a full program. {{PageSyntax}} :: '''SUB Procedure_name''' [(''parameter''[, ''list''...])] :: ... :: ... 'procedure variable definitions and statements :: ... :: '''END SUB''' {{Parameters}} * Parameters passed after the procedure call must match the variable types in the SUB parameters in order. * If there are no ''parameter''s passed or they are...")
 
No edit summary
Line 1: Line 1:
A '''SUB''' procedure is a procedure within a program that can calculate and return multiple parameter values just like a full program.
'''Subs''', short for subroutines, are like [[statement]]s but user-defined. You define a sub by using the [[statement]] {{KW|SUB}} and when called it will execute the code within the SUB until it reaches {{KW|END SUB}} or {{KW|EXIT SUB}}.




{{PageSyntax}}
The {{KW|CALL}} statement can be used to execute the code of a sub but is not really needed, when CALL is used the [[argument]]s need to be enclosed with paranteses.
:: '''SUB Procedure_name''' [(''parameter''[, ''list''...])]
:: ...
:: ... 'procedure variable definitions and statements
:: ...
:: '''END SUB'''




{{Parameters}}
Subs do not return a value, however; altering the variables that are used as arguments within the sub will cause the same changes to the variables outside the sub. This also applies to user-defined [[function (explanatory)|function]]s. Variables that are not arguments of the sub will not be changed if used within the sub unless they are {{KW|SHARED}}.
* Parameters passed after the procedure call must match the variable types in the SUB parameters in order.
* If there are no ''parameter''s passed or they are [[SHARED]] the parameters and parenthesis are not required in the procedure.
* Parameter [[Variable]] names in the procedure do not have to match the names used in the [[CALL]], just the value types.




{{PageDescription}}
The subs has to be located after all other code, this also applies to user-defined [[function (explanatory)|function]]s.
* All [[$DYNAMIC|dynamic]] [[variable]] values return to 0 or null strings when the procedure is exited except for [[STATIC]] variable values.
* SUB procedures can return multiple values through the parameters unlike functions.
* SUB procedures return to the next code statement after the call in the main or other procedures.
* [[EXIT]] SUB can be used to exit early or to exit before [[GOSUB]] procedures using [[RETURN]].
* [[TYPE]] and [[DECLARE LIBRARY]] declarations can be made inside of SUB procedures in QB64 only.
* SUB procedures can save program memory as all memory used in a SUB is released on procedure exit except for [[STATIC]] values.
* [[_DEFINE]] can be used to define all new or old QB64 variable [[TYPE]] definitions instead of DEF***.
* [[$INCLUDE]] text library files with needed SUB and [[FUNCTION]] procedures can be included in programs after all sub-procedures.
* '''QB64 ignores all procedural DECLARE statements!''' Define all ''parameter'' [[TYPE]]s in the SUB procedure.
*  '''Images are not deallocated when the [[SUB]] or [[FUNCTION]] they are created in ends. Free them with [[_FREEIMAGE]].'''




''Example 1:'' Text [[PRINT]] screen centering using [[PEEK]] to find the SCREEN mode width. Call and SUB procedure code:
{{PageExamples}}
{{CodeStart}} '' ''
''Example 1:'' Demonstration of some subs.
{{Cl|DEFINT}} A-Z
{{CodeStart}}
{{Cl|SCREEN}} 13
printsometext
Center 10, 15, "This text is centered." ' example module sub call
{{Cl|CALL}} printmoretext
{{Cl|END}}


{{Cl|DEFINT}} A-Z ' only code allowed before SUB line is a DEF statement or a comment
 
{{Cl|SUB}} Center (Tclr, Trow, Text$)
{{Cl|SUB}} printsometext
Columns = {{Cl|_WIDTH}} / {{Cl|_FONTWIDTH}} 'Convert _WIDTH (in pixels) to width in characters
{{Cl|PRINT}} "This is within the printsometext sub."
Middle = (Columns \ 2) + 1 ' reads any screen mode width
{{Cl|EXIT SUB}}
Tcol = Middle - ({{Cl|LEN}}(Text$) \ 2)
{{Cl|PRINT}} "This is never shown as it encounters EXIT SUB first."
{{Cl|COLOR}} Tclr: {{Cl|LOCATE}} Trow, Tcol: {{Cl|PRINT}} Text$; ' end semicolon prevents screen roll
{{Cl|END SUB}}
{{Cl|END SUB}} '' ''
 
{{Cl|SUB}} printmoretext
{{Cl|PRINT}} "This is within the printmoretext sub."
{{Cl|END SUB}}
{{CodeEnd}}
{{CodeEnd}}


:''Explanation:'' The procedure centers text printed to the screen. The parameters are the text color, row and the text itself as a string or string variable. The maximum width of the screen mode in characters is found and divided in half to find the center point. The text string's length is also divided in half and subtracted from the screen's center position. The procedure will also work when the [[WIDTH]] statement has been used. When adding variables to Text$ use the + concatenation operator. Not semicolons!


''Example 2:'' Variables that are used as arguments changes outside the sub when they are changed within the sub.
{{CodeStart}}
demo hal, bal 'the variables hal and bal are used as arguments when calling the sub.


''Example 2:'' SUB and [[FUNCTION]] procedures always return to the place they were called in the main or other sub-procedures:
{{Cl|PRINT}} hal, bal 'the variables have now been changed by the sub.
{{CodeStart}} '' ''
a = 10
Add1 a
{{Cl|PRINT}} a  'Add1 returns final 'a' value here


{{Cl|END}}
hal = 0
bal = 0


{{Cl|SUB}} Add1 (n)
demo 1, 2
n = n + 1
 
Add2 n
{{Cl|PRINT}} hal, bal 'the variables have not been changed by the sub as the variables wasn't used as arguments.
{{Cl|PRINT}} "exit 1"
 
{{Cl|END SUB}}
{{Cl|SUB}} demo (hal, bal)
 
hal = 3
bal = 4


{{Cl|SUB}} Add2 (m)
m = m + 2
{{Cl|PRINT}} "exit 2"
{{Cl|END SUB}}
{{Cl|END SUB}}
{{CodeEnd}}
{{CodeEnd}}
{{OutputStart}}exit 2
exit 1
13
{{OutputEnd}}
: ''Note:'' Parameter '''a''' is used to call the sub-procedures even though parameters '''n''' and '''m''' are used internally.




''See also:''
* [[FUNCTION]], [[CALL]]
* [[BYVAL]], [[SCREEN (statement)]]
* [[EXIT]], [[END]]


{{PageSeeAlso}}
* [[SUB]], [[FUNCTION]]
* [[Function (explanatory)]], [[Statement]]
* [[Argument]]


{{PageNavigation}}
{{PageNavigation}}

Revision as of 00:55, 22 December 2022

Subs, short for subroutines, are like statements but user-defined. You define a sub by using the statement Template:KW and when called it will execute the code within the SUB until it reaches Template:KW or Template:KW.


The Template:KW statement can be used to execute the code of a sub but is not really needed, when CALL is used the arguments need to be enclosed with paranteses.


Subs do not return a value, however; altering the variables that are used as arguments within the sub will cause the same changes to the variables outside the sub. This also applies to user-defined functions. Variables that are not arguments of the sub will not be changed if used within the sub unless they are Template:KW.


The subs has to be located after all other code, this also applies to user-defined functions.


Examples

Example 1: Demonstration of some subs. 

printsometext
CALL printmoretext


SUB printsometext
PRINT "This is within the printsometext sub."
EXIT SUB
PRINT "This is never shown as it encounters EXIT SUB first."
END SUB

SUB printmoretext
PRINT "This is within the printmoretext sub."
END SUB


Example 2: Variables that are used as arguments changes outside the sub when they are changed within the sub. 

demo hal, bal 'the variables hal and bal are used as arguments when calling the sub.

PRINT hal, bal 'the variables have now been changed by the sub.

hal = 0
bal = 0

demo 1, 2

PRINT hal, bal 'the variables have not been changed by the sub as the variables wasn't used as arguments.

SUB demo (hal, bal)

hal = 3
bal = 4

END SUB



See also

Navigation:
Main Page with Articles and Tutorials
Keyword Reference - Alphabetical
Keyword Reference - By usage
Report a broken link
Retrieved from "https://qb64phoenix.com/qb64wiki/index.php?title=Sub_(explanatory)&oldid=5431"