SUB/ENDSUB

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

  • CALL SUB