DOS batch function definition and usage _dos/bat

What It is, why it ' s important and I to write your own.

Description:the assumption is:a Batch script snippet can be named A function when:

1.. it has a callable entrance point.
2. On completion execution continues right after the command that initially called the function.
3. It works the same no matter from where it's being called, even when it calls itself.
4. The variables used within a function do does not conflict with variables outside the function.
5.. It exchanges data with the calling code strictly through input and output variables or a return code.

The benefits behind functions are:

1.Keep the main script clean
2.Hide complexity in reusable functions
3.Test functions independently from the main script
4.ADD more functionality to your batch script simply by adding more functions at the bottom
5.Don ' t worry about the function implementation, just test it and use it

Create a function What is a function?
Call a function how to invoke a function?
Example-calling a Function a Example showing how it works.
Passing function Arguments How do I Arguments to the function?
Parsing function Arguments How to retrieve function Arguments within the function?
Example-function with Arguments a Example showing how it works.
Returning values the Classic Way the Classic Way of returning values and the limitations.
Returning Values via References let's caller determine how to return the function result and avoid the need of dedicated Variables.
Example-returning Values using Variable Reference an Example showing to it works.
Local Variables in functions how to avoid name conflicts and keep variable The local to the function?
Returning local Variables, how do I pass return values over the endlocal barrier?
Recursive functions Tadaaah!!!
Summary defining a standard format for a DOS batch function
DOS batch-function Tutorial What It is, why it ' s important and I to write your own.

Create a function-what is a Function
Description:in DOS Write a function by surrounding a group's command by a label and a goto:eof command. A single batch file can contain multiple functions defined as this. The label becomes the function name.
Script:

Copy Code code as follows:

: Mydosfunc-here starts my function identified by it ' s label
Echo. Here's the Mydosfunc function is executing a group of commands
Echo. It could do a lot of things
Goto:eof

Call a function-how to invoke a Function
Description:a function can is called with the call command followed by the function label.
Script:01.
Call:mydosfunc

Example-calling a function-an Example showing how it works
Description:the use of batch functions'll divide the script into two sections.

1.The main script:starting at line 1 ending and a goto:eof command that terminates the script.
2.The function section:filling The second half of the batch file with one or more functions to is callable from the main Script.

Script:

Copy Code code as follows:

@echo off
Echo.going to execute Mydosfunc
Call:mydosfunc
Echo.returned from Mydosfunc

Echo.&pause&goto:eof

::--------------------------------------------------------
::--Function section starts below
::--------------------------------------------------------

: Mydosfunc-here starts my function identified by it ' s label
Echo. Here's the Mydosfunc function is executing a group of commands
Echo. It could do a lot of things
Goto:eof

Script Output:script Output
Going to execute Mydosfunc
Here's the Mydosfunc function is executing a group of commands
It could do a lot of things
Returned from Mydosfunc
Press any key to continue ...

Passing function Arguments-how to pass Arguments to the function
Description:just as the DOS batch file itself can have arguments, a function can is called with arguments in a similar WA Y. Just list all arguments after the "function name in" Call command.
Use a spaces or a comma to separate arguments.
Use double quotes for string arguments with spaces.
Script:

Copy Code code as follows:

Call:mydosfunc Yeepee
Call:mydosfunc "For Me"
Call:mydosfunc, "For Me"

Parsing function Arguments-how to retrieve function Arguments within the function
Description:just as the DOS batch file itself retrieves arguments via%1â¦%9 a function can parse it ' s arguments the S Ame Way. The same rules apply.
Let ' s modify we previews example to use arguments.
To strip of the "double quotes in" arguments value the tilde modifier, i.e. use%~2 instead of%2.
Script:

Copy Code code as follows:

: Mydosfunc-here starts mydosfunc identified by it ' s label
Echo.
Echo. Here's the Mydosfunc function is executing a group of commands
Echo. It could do%~1 of things%~2.
Goto:eof

Example-function with Arguments-an Example showing and it works
Description:the following example demonstrates how to pass arguments into a DOS function. The The:mydosfunc function is being the called multiple times with different arguments.

Note:the Mydosfunc doesn ' t use double quotes for the second argument. Subsequently "for" and "me" would be handled as two separate arguments, whereas the third argument "me" are not being used W Ithin the function.
Script:

Copy Code code as follows:

@echo off
Echo.going to execute mydosfunc with different arguments
Call:mydosfunc Yeepee
Call:mydosfunc "For Me"
Call:mydosfunc, "For Me"
Call:mydosfunc 100,for Me
Echo.&pause&goto:eof

::--------------------------------------------------------
::--Function section starts below
::--------------------------------------------------------

: Mydosfunc-here starts my function identified by it ' s label
Echo.
Echo. Here's the Mydosfunc function is executing a group of commands
Echo. It could do%~1 of things%~2.
Goto:eof

Script Output:script Output
Going to execute mydosfunc with different arguments

Here's the Mydosfunc function is executing a group of commands
It could do things yeepee.

Here's the Mydosfunc function is executing a group of commands
It could do the things for me.

Here's the Mydosfunc function is executing a group of commands
It could do the things for me.

Here's the Mydosfunc function is executing a group of commands
It could do the things for.

Press any key to continue ...

Returning values the Classic way-the Classic Way of returning Values and the limitations
Description:the call command doesn ' t support return values as known by the other programming languages.
The classic walkaround is to have the function store the return value into a environment variable. The calling script can be variable when the function returns. The:mygetfunc function below demonstrates how the variable var1 gets the ' dostips ' string assigned which can then be used In the calling function.

Note:the var1 variable is reserved to this particular function. Any data stored in VAR1 by the calling function before Calling:mygetvar would be overwritten.
Usage:

Copy Code code as follows:

Set "Var1=some Hopefully not important string"
Echo.var1 Before:%var1%
Call:mygetfunc
Echo.var1 after:%var1%

Script:

Copy Code code as follows:

: Mygetfunc-get A value
Set "Var1=dostips"
Goto:eof

Script Output:script Output
Var1 Before:some hopefully not important string
Var1 after:dostips

Returning Values via References-let the caller determine how to return the function result and avoid the need of Dedicat Ed variables
Description:instead of using "global" variables for return value, the function can be use one of it ' s arguments as variable Reference. The caller can then pass a variable name to the function and the function can store the "result into" this variable making u SE of the command line expansion of the command processor:

Note:the var1 variable is isn't reserved for this articular function. Any variable can is passed to the function the caller has full control.
Usage:

Copy Code code as follows:

Call:mygetfunc var1
Echo.var1 after:%var1%

Script:

Copy Code code as follows:

: mygetfunc-passing a variable by reference
Set "%~1=dostips"
Goto:eof

Script Output:script Output
Var1 after:dostips

Example-returning Values using Variable reference-an Example showing how it works
Description:this code shows how the VAR1 variable are being passed into A:mygetfunc function simply by passing the VARIAB Le name. Within the:mygetfunc function The command processor works as this:
1.Reads the set command into Memory:set "%~1=dostips"
2.Expand the variables, i.e%~1 like This:set "Var1=dostips"
3.Finally Execute the command and assign the new string to Var1

Script:

Copy Code code as follows:

@echo off

Set "Var1=cmdtips"
Echo.var1 Before:%var1%
Call:mygetfunc var1
Echo.var1 after:%var1%

Echo.&pause&goto:eof

::--------------------------------------------------------
::--Function section starts below
::--------------------------------------------------------

: mygetfunc-passing a variable by reference
Set "%~1=dostips"
Goto:eof

Script Output:script Output
Var1 before:cmdtips
Var1 after:dostips

Press any key to continue ...

Local Variables in functions-how to avoid name conflicts and keep variable The local to the function
Description:the SETLOCAL causes the command processor to backup all environment variables. The variables can is restored by calling Endlocal. Changes made im between are the local to the current batch. Endlocal is automatically being called the "end of" The batch file is reached, i.e. by calling Goto:eof.
Localizing variables with SETLOCAL allows using variable names within a function freely without worrying about name Confli CTS with variables used outside the function.
Script:

Copy Code code as follows:

@echo off

Set "Astr=expect no changed, even if used in function"
Set "Var1=no change for this one. Now what? "
Echo.astr Before:%astr%
Echo.var1 Before:%var1%
Call:mygetfunc var1
Echo.astr after:%astr%
Echo.var1 after:%var1%

Echo.&pause&goto:eof

::--------------------------------------------------------
::--Function section starts below
::--------------------------------------------------------

: mygetfunc-passing a variable by reference
SETLOCAL
Set "Astr=dostips"
Set "%~1=%astr%"
Endlocal
Goto:eof

Script Output:script Output
AStr Before:expect no changed, even if used in function
Var1 Before:no change to this one. Now what?
AStr After:expect no changed, even if used in function
Var1 After:no change to this one. Now what?

Press any key to continue ...

Returning local variables-how the endlocal barrier
Description:the question Is:when localizing a function via SETLOCAL and endlocal, how to return a value, is Calcula Ted before executing endlocal when is endlocal restores all variables the back to it original state?
The answer comes with "variable expansion". The command processor expands all variables of a command before executing the command. Letting the command processor executing endlocal and a SET command at once solves the problem. Commands can be grouped within brackets.
Script:

Copy Code code as follows:

@echo off

Set "Astr=expect no changed, even if used in function"
Set "Var1=expect changed"
Echo.astr Before:%astr%
Echo.var1 Before:%var1%
Call:mygetfunc var1
Echo.astr after:%astr%
Echo.var1 after:%var1%

Echo.&pause&goto:eof

::--------------------------------------------------------
::--Function section starts below
::--------------------------------------------------------

: mygetfunc-passing a variable by reference
SETLOCAL
Set "Astr=dostips"
(endlocal
Set "%~1=%astr%"
)
Goto:eof

: mygetfunc2-passing a variable by reference
SETLOCAL
Set "Astr=dostips"
Endlocal&set "%~1=%astr%" &rem this ALSO works FINE
Goto:eof

Script Output:script Output
AStr Before:expect no changed, even if used in function
VAR1 Before:expect changed
AStr After:expect no changed, even if used in function
Var1 after:dostips

Press any key to continue ...

Recursive Functions-tadaaah!!!
Description:being able to completely encapsulate the "body of" a function by keeping variable The local to the function and invisible to the caller we are now able to call a function recursively making sure all level of recursion works with Its own set of variables even thought variable names are being reused.

Example:the next Example below shows to calculate a Fibonacci number recursively. The recursion SS-Fibonacci algorism reaches a number greater or equal to a given input number.
The example starts with the numbers 0 and 1 The:myfibo function calls itself recursively to calculate the next Fibonacci Number until it finds the Fibonacci number greater or equal 1000000000.

The "the" Myfibo function is the name of the "variable to store", the output in. This variable must is initialized to the Fibonacci number to start with and is used as current Fibonacci Calling the function and would be set to the subsequent Fibonacci number when the function returns.
Script:

Copy Code code as follows:

@echo off

Set "Fst=0"
Set "Fib=1"
Set "limit=1000000000"
Call:myfibo fib,%fst%,%limit%
Echo. The next Fibonacci number greater or equal%limit% is%fib%.

Echo.&pause&goto:eof

::--------------------------------------------------------
::--Function section starts below
::--------------------------------------------------------

: Myfibo--Calculate recursively the next Fibonacci number greater or equal to a limit
::--%~1:return variable reference and current Fibonacci number
::--%~2:previous value
::--%~3:limit
SETLOCAL
set/a "Number1=%~1"
set/a "Number2=%~2"
set/a "Limit=%~3"
set/a "Numbern=number1 + Number2"
if/i%numbern% LSS%limit% Call:myfibo numbern,%number1%,%limit%
(endlocal
IF "%~1" NEQ "" SET "%~1=%numbern%"
)
Goto:eof

Script Output:script Output
The next Fibonacci number greater or equal 1000000000 is 1134903170.

Press any key to continue ...

Summary-defining a standard format for a DOS batch function
Description:with the information learned in this section we can define a standard format for a DOS batch functions as Sho WN below.
Also Check out the rich set of ready to use DOS functions provided by the Dostips.com function library.
Script:

Copy Code code as follows:

: Myfunctionname--Function description here
::--%~1:argument description here
SETLOCAL
Rem.--function body
Set localvar1= ...
Set localvar2= ...
(Endlocal & REM--Return VALUES
IF "%~1" Neq "" SET%~1=%localvar1%
IF "%~2" Neq "" SET%~2=%localvar2%
)
Goto:eof

Source: http://www.dostips.com/DtTutoFunctions.php