Q(uick)BASIC Statement: DECLARE

Quick View

DECLARE (BASIC) Statement

A non-executable statement that declares references to BASIC procedures and invokes argument type checking

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax

DECLARE {FUNCTION | SUB} name [([parameterlist])]

Description/Parameter(s)

name	The name of the procedure.
parameterlist	One or more variables that specify parameters to be passed to the procedure when it is called:
variable[( )] [AS type] [, variable[( )] [AS type]]…
variable	A Basic variable name.
type	The data type of the variable (INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined data type). ANY allows any data type.

DECLARE is required if you call SUB procedures without CALL. QBasic automatically generates DECLARE statements when you save your program.

Example

The program REMLINE.BAS illustrates declaring FUNCTION and SUB procedures. To view or run this program, load REMLINE.BAS using the Open command from the File menu.

Syntax

DECLARE {FUNCTION | SUB} name [([parameterlist])]

Description/Parameter(s)

name	The procedure's name. The name is limited to 40 characters. FUNCTION names can end in one of the type-declaration characters (%, &, !, #, or $) to indicate the type of value returned.
parameterlist	A list of parameters indicating the number and type of arguments used when calling the procedure. Syntax is shown below. Only the number and type of the arguments are significant.

For calls within BASIC, the DECLARE statement is required only if you call SUB procedures without the CALL keyword, or if you invoke a FUNCTION defined in another module.

A DECLARE statement also causes the compiler to check the number and type of arguments used to invoke the procedure. QuickBASIC automatically generates DECLARE statements when you save your program while working in the environment. The DECLARE statement can appear only in module-level code (not in a SUB or FUNCTION) and affects the entire module.

The parameterlist serves as a prototype for checking the number and type of the arguments in SUB and FUNCTION calls. It has the following syntax:

variable[AS type][,variable[AS type]]…

A variable is any valid BASIC variable name. If the variable is an array, it may be followed by the number of dimensions in parentheses:

DECLARE SUB DisplayText (A(2) AS STRING)
DIM Text$(100,5)
⋮
CALL DisplayText(Text$())

The number of dimensions is optional.

The type is either INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined type. Again, only the number and types of arguments are significant.

Note:

You cannot have fixed-length strings in DECLARE statements because only variable-length strings can be passed to SUB and FUNCTION procedures. Fixed-length strings can appear in an argument list but are converted to variable-length strings before being passed.

A variable's type can also be indicated by including an explicit type character ( %, &, !, #, or $) or by relying on the default type.

The form of the parameter list determines whether or not argument checking is done, as shown in the following list:

Declaration	Meaning
DECLARE SUB First	You may only omit the parentheses if the SUB or FUNCTION is separately compiled. No argument checking is done.
DECLARE SUB First ()	First has no parameters. Arguments in a CALL to First are flagged as an error. An empty parameter list indicates that the SUB or FUNCTION has no parameters.
DECLARE SUB First (X AS LONG)	First has one long-integer parameter. The number and type of the arguments in each CALL or invocation are checked when the parameter list appears in the DECLARE.

Example

DECL_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates the DECLARE statement for BASIC procedures. To look at the program in the View window and, optionally, to run it, load the program using the File menu's Open Program command.In the program, use of the DECLARE statement allows a SUB to be invoked without using the CALL keyword.

Syntax

DECLARE {FUNCTION | SUB} name [([parameterlist])]

Description/Parameter(s)

The argument name is limited to 40 characters. FUNCTION procedure names can end in one of the type-declaration characters (%, &, !, #, @, or $) to indicate the type of value returned.
The parameterlist serves as a prototype for checking the number and type of the arguments in SUB and FUNCTION procedure calls. Only the number and type of the arguments are significant. It has the following syntax:

[BYVAL] variable[AS type][,[BYVAL] variable[AS type]]…
[BYVAL]	Defines the variable as being passed by value rather than by reference (the default). BYVAL can be used only with simple numeric types (INTEGER, LONG, SINGLE, DOUBLE, or CURRENCY).
variable	Any valid BASIC variable name. If the variable is an array, it can be followed by the number of dimensions in parentheses, as in this fragment:
	DECLARE SUB DisplayText (a() AS STRING) DIM Text$(100, 5) ⋮ CALL DisplayText(Text$())
	The number of dimensions is optional.
type	Is INTEGER, LONG, SINGLE, DOUBLE, CURRENCY, STRING, or a user-defined type. Again, only the number and types of arguments are significant.
	A variable's type also can be indicated by including an explicit type character (%, &, !, #, @, or $) or by relying on the default type.

Usage Notes

If a parameter is passed by reference, any change to the parameter's value inside the procedure changes its value in the calling program.
If a parameter is passed by value, any changes to the parameter's value inside the procedure is local to that procedure and does not affect its value in the calling program.
For calls within BASIC, the DECLARE statement is required only if you call SUB procedures without the CALL keyword, or if you invoke a FUNCTION procedure defined in another module. For more information about invoking procedures without CALL, see Chapter 2, "SUB and FUNCTION Procedures" in the Programmer's Guide.
A DECLARE statement also causes the compiler to check the number and type of arguments used to invoke the procedure. QBX automatically generates DECLARE statements when you save your program while working in the environment. The DECLARE statement can appear only in module-level code (not in a SUB or FUNCTION procedure) and affects the entire module.
The form of the parameter list determines whether or not argument checking is done, as shown in the following list:

Declaration	Meaning
DECLARE SUB First	You can omit the parentheses only if the SUB or FUNCTION procedure is separately compiled. No argument checking is done.
DECLARE SUB First ()	First has no parameters. Arguments in a call to First generate an error. An empty parameter list indicates that the SUB or FUNCTION procedure has no parameters and that argument checking should be done.
DECLARE SUB First (X AS LONG)	First has one long-integer parameter. The number and type of the arguments in each call or invocation are checked when the parameter list appears in the DECLARE statement.

Important

You cannot have fixed-length strings in DECLARE statements. Only variable-length strings can be passed to SUB and FUNCTION procedures. Fixed-length strings can appear in an argument list but are converted to variable-length strings before being passed.
You can have arrays containing fixed-length strings in DECLARE statements. The lengths of the array in the CALL statement and the declaration must match.

Examples

Example 1 uses the DECLARE statement to allow a SUB procedure to be invoked without using the CALL keyword.

DECLARE SUB Sort (a() AS INTEGER, N AS INTEGER)
DIM Array1(1 TO 20) AS INTEGER
DIM I AS INTEGER
'Generate 20 random numbers.
RANDOMIZE TIMER
FOR I% = 1 TO 20
   Array1(I%) = INT(RND * 100)
NEXT I%
 
'Sort the array, calling Sort without the CALL keyword. Notice the
'absence of parentheses around the arguments in the call to Sort.
Sort Array1(), 20
 
'Print the sorted array.
CLS
FOR I% = 1 TO 20
   PRINT Array1(I%)
NEXT I%
END

'Sort procedure.
SUB Sort (a%(), N%)
 
   FOR I% = 1 TO N% - 1
      FOR J% = I% + 1 TO N%
         IF a%(I%) > a%(J%) THEN SWAP a%(I%), a%(J%)
      NEXT J%
   NEXT I%
 
END SUB

Example 2 uses the [BYVAL] keyword to pass an argument by value.

DECLARE SUB Mult (BYVAL X!, Y!)
CLS
a = 1
b = 1
PRINT "Before subprogram call, A = "; a; ", B ="; b
 
' A is passed by value,  and B is passed by reference:
CALL Mult(a, b)
PRINT "After subprogram call, A ="; a; ", B ="; b
 
END

SUB Mult (BYVAL X, Y)
        X = 2 * X
        Y = 3 * Y
        PRINT "In subprogram, X ="; X; " , Y ="; Y
END SUB