QB64-PE/internal/help/SUB.txt

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''])]


* If there are no ''parameter''s passed or they are [[SHARED]] the parameters and parenthesis are not required in the procedure.
* [[Variable]] names within the procedure do not have to match the names used in the [[CALL]], just the value types.
* The [[IDE]] can create the SUB and [[END SUB]] lines for you. Use the Make SUB option in the Edit Menu. A box will come up for you to enter a name for the SUB. Enter the procedure code between the SUB and [[END SUB]] lines created. '''Code lines before or after the procedure are not permitted except for a DEF default variable [[TYPE]] declaration before the SUB line.'''
* 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.
* [[EXIT]] SUB can be used to exit early or to exit before [[GOSUB]] procedures using [[RETURN]].
* SUB procedures can save program memory as all memory used in a SUB is released on procedure exit except for [[STATIC]] values.
* [[$INCLUDE]] text library files with needed SUB and [[FUNCTION]] procedures can be included in programs after other sub-procedures.
* '''SUB procedures cannot have [[ON]] events, [[DATA]] or [[ON ERROR]] statements inside of them.''' Procedure code can use [[GOSUB]] and [[GOTO]] linenumbers and linelabels inside of the procedure only. '''QB64''' allows [[TYPE]]s and [[DECLARE LIBRARY]] declarations.
* The Qbasic [[IDE]] will [[DECLARE]] a SUB at the top of the module code after it has been [[CALL|referenced]] and the BAS file is saved. 
* Qbasic's [[IDE]] may place a [[DEFINT]], [[DEFSNG]], [[DEFLNG]], [[DEFDBL]] or [[DEFSTR]] statement before the SUB line if it is used in the main module. It may even be the wrong variable type needed. It can be removed or changed if necessary. 
* An uncalled SUB will not be [[DECLARE]]d in Qbasic if it is not used. 
* '''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]].'''
* '''WARNING! Do not place DATA fields after [[SUB]] or [[FUNCTION]] procedures! QB64 will FAIL to compile properly!'''
: Qbasic allowed programmers to add DATA fields anywhere because the [[IDE]] separated the main code from other procedures.


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

DEFINT A-Z ' only code allowed before SUB line is a DEF statement or a comment
{{Cl|SUB}} Center (Tclr, Trow, Text$)
{{Cl|DEF SEG}} = &H40
Columns = {{Cl|PEEK}}(&H4A)
{{Cl|DEF SEG}}
Middle = (Columns \ 2) + 1 ' reads any screen mode width
Tcol = Middle - ({{Cl|LEN}}(Text$) \ 2)
{{Cl|COLOR}} Tclr: {{Cl|LOCATE}} Trow, Tcol: {{Cl|PRINT}} Text$; ' end semicolon prevents screen roll
{{Cl|END SUB}} '' ''
{{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 screenmode 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!


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


{{PageNavigation}}