What it is, why it`s important and how 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 recursively.
4.... the variables used within a function do 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 An Example showing how it works.
Passing Function Arguments How to pass arguments to the function?
Parsing Function Arguments How to retrieve function arguments within the function?
Example - Function with Arguments An Example showing how it works.
Returning Values the Classic Way The classic way of returning values and the limitations.
Returning Values via References Let the caller determine how to return the function result and avoid the need of dedicated variables.
Example - Returning Values using Variable Reference An Example showing how it works.
Local Variables in Functions How to avoid name conflicts and keep variable changes local to the function?
Returning Local Variables How to 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 how to write your own.
Create a Function - What is a function
Description: In DOS you write a function by surrounding a group of command by a label and a GOTO:EOF command. A single batch file can contain multiple functions defined like this. The label becomes the function name.
Script:
:myDosFunc - here starts my function identified by it`s label
echo. here the myDosFunc function is executing a group of commands
echo. it could do a lot of things
GOTO:EOF
</div>
Call a Function - How to invoke a function
Description: A function can be 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 will divide the script into two sections.
1.The main script: starting at line 1 ending with 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 be callable from the main script.
Script:
@echo off
echo.going to execute myDosFunc
call:myDosFunc
echo.returned from myDosFunc
echo.&pause&goto:eof
::--------------------------------------------------------
::-- Function section starts below here
::--------------------------------------------------------
:myDosFunc - here starts my function identified by it`s label
echo. here the myDosFunc function is executing a group of commands
echo. it could do a lot of things
goto:eof
</div>
Script Output: Script Output
going to execute myDosFunc
here 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 be called with arguments in a similar way. Just list all arguments after the function name in the call command.
Use a space or a comma to separate arguments.
Use double quotes for string arguments with spaces.
Script:
call:myDosFunc 100 YeePEE
call:myDosFunc 100 "for me"
call:myDosFunc 100,"for me"
</div>
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 same way. The same rules apply.
Let`s modify our previews example to use arguments.
To strip of the double quotes in an arguments value the tilde modifier, i.e. use %~2 instead of %2.
Script:
:myDosFunc - here starts myDosFunc identified by it`s label
echo.
echo. here the myDosFunc function is executing a group of commands
echo. it could do %~1 of things %~2.
goto:eof
</div>
Example - Function with Arguments - An Example showing how it works
Description: The following example demonstrates how to pass arguments into a DOS function. The :myDosFunc function is being called multiple times with different arguments.
Note: The last call to myDosFunc doesn`t use double quotes for the second argument. Subsequently "for" and "me" will be handled as two separate arguments, whereas the third argument "me" is not being used within the function.
Script:
@echo off
echo.going to execute myDosFunc with different arguments
call:myDosFunc 100 YeePEE
call:myDosFunc 100 "for me"
call:myDosFunc 100,"for me"
call:myDosFunc 100,for me
echo.&pause&goto:eof
::--------------------------------------------------------
::-- Function section starts below here
::--------------------------------------------------------
:myDosFunc - here starts my function identified by it's label
echo.
echo. here the myDosFunc function is executing a group of commands
echo. it could do %~1 of things %~2.
goto:eof
</div>
Script Output: Script Output
going to execute myDosFunc with different arguments
here the myDosFunc fu