DOS Batch - Function Tutorial

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.
TOP
2008-01-01

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:
01.
02.
03.
04.
 :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
TOP
2008-01-01

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
TOP
2008-01-01

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: Download: BatchTutoFunc1.bat

01.
02.
03.
04.
05.
06.
07.
08.
09.
10.
11.
12.
13.
14.
15.
16.
 @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
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 . . .
TOP
2008-01-01

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:
01.
02.
03.
 call:myDosFunc 100 YeePEE
call:myDosFunc 100 "for me"
call:myDosFunc 100,"for me"
TOP
2008-01-01

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:
01.
02.
03.
04.
05.
 :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
TOP
2008-01-01

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: Download: BatchTutoFunc2.bat

01.
02.
03.
04.
05.
06.
07.
08.
09.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
 @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
Script Output:
  Script Output 
going to execute myDosFunc with different arguments

 here the myDosFunc function is executing a group of commands

 it could do 100 of things YeePEE.

 here the myDosFunc function is executing a group of commands

 it could do 100 of things for me.

 here the myDosFunc function is executing a group of commands

 it could do 100 of things for me.

 here the myDosFunc function is executing a group of commands

 it could do 100 of things for.

Press any key to continue . . .
TOP
2008-01-01

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 other programming languages.
The classic walkaround is to have the function store the return value into a environment variable. The calling script can use this 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 for this particular function. Any data stored in var1 by the calling function before calling :myGetVar will be overwritten.
Usage:
01.
02.
03.
04.
 set "var1=some hopefully not important string"
echo.var1 before: %var1%
call:myGetFunc
echo.var1 after : %var1%
Script:
01.
02.
03.
 :myGetFunc    - get a value
set "var1=DosTips"
goto:eof
Script Output:
  Script Output 
var1 before: some hopefully not important string

var1 after : DosTips
TOP
2008-01-01

Returning Values via References - Let the caller determine how to return the function result and avoid the need of dedicated variables

Description: Instead of using "global" variables for return value, the function can 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 use of the command line expansion of the command processor:

Note: The var1 variable is not reserved for this articular function. Any variable can be passed to the function the caller has full control.
Usage:
01.
02.
 call:myGetFunc var1
echo.var1 after : %var1%
Script:
01.
02.
03.
 :myGetFunc    - passing a variable by reference
set "%~1=DosTips"
goto:eof
Script Output:
  Script Output 
var1 after : DosTips
TOP
2008-01-01

Example - Returning Values using Variable Reference - An Example showing how it works

Description: This code shows how the var1 variable is being passed into a :myGetFunc function simply by passing the variable name. Within the :myGetFunc function the command processor works like 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: Download: BatchTutoFunc3.bat

01.
02.
03.
04.
05.
06.
07.
08.
09.
10.
11.
12.
13.
14.
15.
16.
17.
 @echo off

set "var1=CmdTips"
echo.var1 before: %var1%
call:myGetFunc var1
echo.var1 after : %var1%

echo.&pause&goto:eof

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

: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 . . .
TOP
2008-01-01

Local Variables in Functions - How to avoid name conflicts and keep variable changes local to the function

Description: The SETLOCAL causes the command processor to backup all environment variables. The variables can be restored by calling ENDLOCAL. Changes made im between are local to the current batch. ENDLOCAL is automatically being called when 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 conflicts with variables used outside the function.
Script: Download: BatchTutoFunc4.bat

01.
02.
03.
04.
05.
06.
07.
08.
09.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
 @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 here
::--------------------------------------------------------

: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 for this one.  Now what?

aStr after : Expect no changed, even if used in function

var1 after : No change for this one.  Now what?

Press any key to continue . . .
TOP
2008-01-01

Returning Local Variables - How to pass return values over the ENDLOCAL barrier

Description: The question is: When localizing a function via SETLOCAL and ENDLOCAL, how to return a value that was calculated before executing ENDLOCAL when ENDLOCAL restores all variables back to its 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: Download: BatchTutoFunc5.bat

01.
02.
03.
04.
05.
06.
07.
08.
09.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
 @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 here
::--------------------------------------------------------

: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 . . .
TOP
2008-01-01

Recursive Functions - Tadaaah!!!

Description: Being able to completely encapsulate the body of a function by keeping variable changes local to the function and invisible to the caller we are now able to call a function recursively making sure each level of recursion works with its own set of variables even thought variable names are being reused.

Example: The next example below shows how to calculate a Fibonacci number recursively. The recursion stops when the 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 first argument of the myFibo function is the name of the variable to store the output in. This variable must be initialized to the Fibonacci number to start with and will be used as current Fibonacci number when calling the function and will be set to the subsequent Fibonacci number when the function returns.
Script: Download: BatchTutoFuncRecurs.bat

01.
02.
03.
04.
05.
06.
07.
08.
09.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
 @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 here
::--------------------------------------------------------

: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 . . .
TOP
2008-01-01

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 shown below.
Also check out the rich set of ready to use DOS functions provided by the DosTips.com function library.
Script: Download: BatchFunctionTmpl.bat

01.
02.
03.
04.
05.
06.
07.
08.
09.
10.
11.
 :myFunctionName    -- function description here
::                 -- %~1: argument description here
SETLOCAL
REM.--function body here
set LocalVar1=...
set LocalVar2=...
(ENDLOCAL & REM -- RETURN VALUES
    IF "%~1" NEQ "" SET %~1=%LocalVar1%
    IF "%~2" NEQ "" SET %~2=%LocalVar2%
)
GOTO:EOF

出处：http://www.dostips.com/DtTutoFunctions.php

DOS批处理 - 函数教程的更多相关文章

  1. DOS批处理高级教程（还不错）（转）

    前言 目录 第二节 常用特殊符号     1.@  命令行回显屏蔽符     2.%  批处理变量引导符     3.>   输出重定向符     4.>>  输出重定向符     ...

  2. DOS批处理高级教程

    转载-->http://blog.csdn.net/lanbing510/article/details/7461073 前言 本教程主要引用伤脑筋版主的系列文章,同时参考引用[英雄]教程等其他 ...

  3. cocos2d-x教程3：用php或DOS批处理命令来转换文件和解压缩zip

    在cocos2d-x使用中,须要不停的转换文件和压缩或解压文件.假设全人工来做,太麻烦了,且easy出错. 我如今把一些用的到批处理贴出来,供大家使用 自己主动把dat文件按数字排序重命名gz.DOS ...

  4. 【转载】BAT 批处理脚本教程

    来源:http://www.cnblogs.com/glaivelee/archive/2009/10/07/1578737.html BAT 批处理脚本 教程   第一章 批处理基础第一节 常用批处 ...

  5. BAT 批处理脚本 教程 【转】

    BAT 批处理脚本 教程 第一章 批处理基础 第一节 常用批处理内部命令简介 批处理定义:顾名思义,批处理文件是将一系列命令按一定的顺序集合为一个可执行的文本文件,其扩展名为BAT或者CMD.这些命令 ...

  6. 转：windows BAT 批处理脚本教程

    转自:http://www.cnblogs.com/mq0036/p/3412171.html BAT 批处理脚本教程 第一章 批处理基础第一节 常用批处理内部命令简介 批处理定义:顾名思义,批处理文 ...

  7. 用DOS批处理实现FTP自动上传、下载、清理文件

    用DOS批处理实现FTP自动上传.下载.清理文件 最近好像特别的忙,好久没来写点东西了,今天写了一个利用批处理程序完成FTP自动上传.下载.清理文件的程序.赶紧 记录下来,以备日后之用.功能介绍:自动 ...

  8. DOS批处理的字符串功能

    原文:DOS批处理的字符串功能 DOS批处理的字符串功能 批处理有着具有非常强大的字符串处理能力,其功能绝不低于C语言里面的字符串函数集.批处理中可实现的字符串处理功能有:截取字符串内容.替换字符串特 ...

  9. 利用DOS批处理实现定时关机操作

    10月1放假回来,寝室晚上10:30就停电了,最无法让人理解的是第二天早上8:00才来电.原来晚上电脑都是不关机的,开着WiFi一直到天亮,可是现在不行了,电脑如果一直开着第二天早上起来电脑肯定没电, ...

随机推荐

  1. thinkphp导出报表

    这是我写的一个方法,这个方法可以直接使用在你的代码上.下面我画红色的就是要修改或者删除的.public function import(){ /*创建PHPEXCLE读取,默认excel2007,最好 ...

  2. LeetCode 318. Maximum Product of Word Lengths （状态压缩）

    题目大意:给出一些字符串,找出两个不同的字符串之间长度之积的最大值,但要求这两个字符串之间不能拥有相同的字符.(字符只考虑小写字母). 题目分析:字符最多只有26个,因此每个字符串可以用一个二进制数来 ...

  3. 深入理解$watch ，$apply 和 $digest --- 理解数据绑定过程——续

    Angular什么时候不会自动为我们$apply呢? 这是Angular新手共同的痛处.为什么我的jQuery不会更新我绑定的东西呢?因为jQuery没有调用$apply,事件没有进入angular ...

  4. 循环大法——一次性理清forEach/for-in/for/$each

    国寿的这个项目写得我基础都忘完了 近期会把vue和基础都并行复习.学习 forEach 适用于调用数组的每个元素,并将元素传递给回调函数,但是空数组是不会执行回调函数的.forEach适用于集合中的对 ...

  5. PHP:第一章——php中的变量001 /普通赋值/引用赋值/php变量的检查与销毁

    <?php //php中的变量: //php中的变量用一个美元符$后面紧跟着变量名来表示,变量名是区分大小写的. //有效的变量只能是字母或者下划线开头,后面跟任意数量的字母.数字.或者下划线. ...

  6. windows下运用批处理实现一键自动开启多个应用

    工作时,我每天早上到公司,打开自己的电脑,都会有几个固定的软件(myeclipse,飞信,firefox,foxmail等).文件夹和文件需要打开,每天如此,感到很烦,浪费时间做重复的工作,于是想到一 ...

  7. Pycharm(二)创建项目

    首次打开就是这样,可以创建新项目,打开一个项目,也可以从版本控制打开项目 我们就新建项目吧,Create New Project 创建项目就是这样了 Location:项目路径. Interprete ...

  8. gitignore中常见需要被无视的文件

    gitignore中常见的需要被忽略的文件:例如各个系统.一些软件会自动生成的文件,主要适用于web项目. 复制后,保存进.gitignore文件中即可. # Project node_modules ...

  9. 指针和const一些注意事项

    1.常量指针(底层const) 指向常量的指针,指针所指向的对象的值无法被修改,若想存放常量对象的地址,只能使用指向常量的指针. 2.指针常量(顶层const) 指针本身是常量,指针本身的值不可修改. ...

  10. SharePoint 2013的100个新功能之内容管理（四）

    一:脚本编辑器Web部件 新的脚本编辑器Web部件表现为插入标签页下的Ribbon中的"嵌入的代码",可以使用户在SharePoint网站页面中添加HTML或Javascript或 ...