See also: CALL, GOTO, and RETURN.

 

File Completion Syntax:

 

The default filename completion syntax is: [1] dirs btm cmd bat [2*] *

 

Usage:

 

GOSUB can only be used in batch files.

 

TCC allows subroutines in batch files. A subroutine must start with a label (a colon [:] followed by a label name) which appears on a line by itself, and cannot be included a command group. Case differences are ignored when matching labels. The subroutine must end with a RETURN statement.

 

The subroutine is invoked with a GOSUB command from another part of the batch file. After the RETURN, processing will continue with the command following the GOSUB command. For example, the following batch file fragment calls a subroutine which displays the directory and returns:

 

echo Calling a subroutine

gosub subr1

echo Returned from the subroutine

quit

:subr1

dir /a/w

return

 

GOSUB begins its search for the label on the line of the batch file immediately after the GOSUB command. If the label is not found between the current position and the end of the file, GOSUB will restart the search at the beginning of the file. If the label still is not found, the batch file is terminated with the error message "Label not found".

 

You can define GOSUB variables by placing them after the label name on the GOSUB line. For example:

 

Gosub Sub1 abc 15 "Hello World"

 

The variable names are defined on the label line. For example:

 

:Sub1 [str n world]

 

defines three variables - %str (set to "abc"), %n (set to 15), and %world (set to "Hello World"). Note that the square brackets are required on the label line. GOSUB variables are only defined for the duration of the subroutine. They are not inherited by nested GOSUBs, and are destroyed by the RETURN call.

 

If you append a * to the last variable name in the parameter list on the label line, it will be "greedy", and all remaining variables will be assigned to it. For example:

 

gosub sub1 one two three four five

...

:sub1 [arg1 arg2 arg3*]

 

arg3 will be assigned "three four five".

 

If you define GOSUB variables on the label but do not supply them on the GOSUB line, they will be set to an empty string.

 

GOSUB calls with variables are limited to a maximum of 22 levels deep. There is no limit on normal GOSUB calls.

 

GOSUB variables are placed in the environment in a special form for the duration of the subroutine, and will "mask" any environment variables of the same name that existed before the subroutine was called. GOSUB variables can be referenced like normal environment variables, but are not stored in the same way, cannot be modified with the SET, ESET, or UNSET commands, and cannot be used with the DEFINED test of IF, IFF, or @IF.

 

You cannot use SET within a subroutine to change the value of a GOSUB variable. If you attempt to do so, the SET command will set the standard environment variable of the same name, not the GOSUB variable, but this value will be "masked" by the GOSUB variable and will remain inaccessible until the subroutine ends.

 

You can call a subroutine in another file by specifying filename (the name must be enclosed in double quotes. This allows you to create libraries of subroutines, without having to duplicate them in each batch file. For example:

 

gosub "c:\library\batlib.btm" Evaluate [%1 %2 %3]

 

GOSUB saves the IFF and DO states, so IFF and DO statements inside a subroutine won't interfere with statements in the part of the batch file from which the subroutine was called. If the subroutine has executed a SETLOCAL without a matching ENDLOCAL, an ENDLOCAL will be executed before returning to the calling batch file.

 

You cannot RETURN from a GOSUB while inside a DO loop.

 

If TCC reaches the end of the batch file while inside a subroutine, it will automatically return to the command after the GOSUB, just as if an explicit RETURN command had been included as the last line of the file.

 

Subroutines can be nested.

 

See also: user-defined functions.