Format
SUB "subroutinename" [(parm1[[,parm2]...[,parm30]])]
ENDSUB [(parm1[[,parm2]...[,parm30]])]
Description
These two statements are used to declare an ASIC subroutine that can be
called using the ASIC "CALL SUB" statement. An ASIC subroutine is compiled
into an OBJ file. After being compiled, you can then call it from another
ASIC subroutine. See Chapter 10 of the ASIC Manual for more information
about using subroutines.
Only one subroutine can appear in a single source file. When declaring a
subroutine, the SUB statement must be the very first statement in the file,
or ASIC will generate a syntax error. Subroutinename should be a string
constant that will identify the name of the subroutine. Note that
"subroutinename" is case sensitive.
Optionally, up to 30 parameters may be specified for the subroutine, but no
parameters are required.
The last statement executed in a subroutine must be the ENDSUB statement.
This statement ensures a graceful return to the calling program. If the
last statement executed in a subroutine module is not ENDSUB, the results
are unpredictable (you will probably crash your program).
By default, the parameters are passed to the SUB "by value". This means
that the subroutine will copy the parameters to its own memory area, and
will not modify the original parameters in the calling program. This
default behavior is achieved when the ENDSUB statement is specified with no
parameters.
However, if you want the subroutine to update the calling program's
variables, you must include the same list of parameters that appeared on
the SUB statement on the ENDSUB statement. This will cause ASIC to update
the calling program's copy of the variables.
Arrays are not currently supported as parameters for SUB's.
Example
SUB "PrintDollars" (NumToPrint@)
X$=STR$(NumToPrint@)
X$ = LEFT$(X$,16)
X$=LTRIM$(X$)
PRINT X$
NumToPrint@ = 0@
ENDSUB
Assume the above code is saved in a file called TESTSUB.ASI. It should be
compiled with the "Object Output File" compile option.
Continuing with the example, the following code shows the calling program:
PRINT "DOLLAR AMOUNT";
INPUT DOL@
CALL SUB "PrintDollars" (DOL@)
PRINT DOL@
Assume this program is saved in a file called CALLSUB.ASI (Note: both
TESTSUB.ASI and CALLSUB.ASI) are included on the ASIC disk). When
compiling it, be sure that the "Object Output File" compile option is set.
Also, the "obJect Names" Compile Option should be set to "TESTSUB.OBJ". Be
sure that the LINK options are set so that ASIC can find LINK.EXE (see
Chapter 10 for more information). After you compile and link the program,
a file "CALLSUB.EXE" should be created. A sample execution of this program
is shown below:
CALLSUB <enter>
DOLLAR AMOUNT? 530 <enter>
530.00
530.00000
Note that even though the subroutine modified "NumToPrint@" to zero, the
calling program's copy was not changed (it still printed as 530.00000).
This is because the subroutine's ENDSUB statement had no parameters. If
instead, the subroutine's ENDSUB statement was "ENDSUB (NumToPrint@)", then
ASIC would update the calling program's variable. The same program run
(with the new ENDSUB statement) is shown below:
CALLSUB <enter>
DOLLAR AMOUNT? 530 <enter>
530.00
0.00000
As expected, in this example, DOL@ has been set to 0 by "PrintDollars"
updating the corresponding parameter variable "NumToPrint@". (This example
program is included on your ASIC diskette).
Comments
Do not include an "END" statement in your subroutines. This will terminate
your program instead of returning to the calling program. Use ENDSUB
instead.
Do not attempt to LINK and run an ASIC SUBroutine as a standalone program--
it MUST be called from an ASIC program. If you LINK and run it by itself,
you will crash your program and probably have to reboot. This is due to
the ENDSUB statement. One of the machine language instructions generated
for ENDSUB is "RETF". This instruction expects to find the address of the
calling program on the stack. When you run a subroutine as a standalone
program, this address is not found, and the CPU will transfer control to an
unexpected memory location which will usually crash your program.
The "Debugging code" compile option is not supported for SUBroutines. When
you compile source files containing SUB statements, ASIC will force you to
turn off the "Debugging code" option. This means that you cannot use the
debugger on subroutines. However, you can use the debugger with programs
which call subroutines. When tracing through a program and a CALL SUB
statement is reached, the debugger will simply "step over" the statement.
It cannot trace into the SUBroutine. If your subroutine has complex logic
and you want to use the debugger with it, then, write it as a non-
subroutine (leave out SUB/ENDSUB statements). Debug and test it
thoroughly, then, add the SUB/ENDSUB statements and recompile it without
debugging mode.
See Also