|
17 | Batch Functions Explained
18 | Passing Arguments
19 | Most high-level programming languages allow arguments to be passed to
20 | functions 'by value' and 'by reference'. Passing by value means that
21 | the function receives a copy of the arguments value. Any changes made
22 | to this copy by the function do no affect the original variable.
23 | When a variable is passed by reference, the function
24 | receives a pointer to the original variable, and loosely speaking, changes
25 | made to this pointer by the function do affect the original variable.
26 | In the batch programming language variables
27 | are passed by reference. Unfortunately the pointers to the original
28 | variables are read only and consequently cannot be assigned values and
29 | therefore are unable to alter the variable which they point to.
30 | The good news is that with a
31 | little ingenuity, the batch language can be coerced into passing variables
32 | by value and by reference in a similar way to high-level languages
33 | such as C and Visual Basic.
34 | By Value
35 | Below is a very simple example showing how to
36 | pass an argument by value and how that value is then read by the function.
37 |
38 | 1. @echo off & setlocal ENABLEEXTENSIONS
39 | 2. set str=Hello
40 | 3. call :demoA %str%
41 | 4. goto :EOF
42 | 5.
43 | 6. :demoA
44 | 7. echo/%1
45 | 8. goto :EOF
46 |
47 | In line 3, %str% is expanded to Hello,
48 | and then the memory location of where Hello is
49 | actually stored is assigned to %1. Line
50 | 7 then references %1 which is then expanded
51 | to Hello.
52 | If two or more arguments were being passed, they
53 | could be referenced using %2, %3 and
54 | so on, all the way up to %9. If more
55 | than nine variables were being passed, then to reference the tenth,
56 | the shift command
57 | would have to be used.
58 | shift effectively
59 | increments all the pointers. Before
60 | shift is used, %0 points
61 | to the name of the function or routine and %1 points
62 | to the first argument. After shift is
63 | used, %0 points to what %1 used
64 | to point to, %1 points
65 | to what %2 used to point to and so on.
66 | The tenth argument can now be referenced using %9.
67 | By Reference
68 | Here is a slighty different version of the example above. Instead
69 | of passing the value Hello to the function,
70 | the name of a variable that contains Hello is
71 | passed instead.
72 |
73 | 1. @echo off & setlocal ENABLEEXTENSIONS
74 | 2. set str=Hello
75 | 3. call :demoB str
76 | 4. goto :EOF
77 | 5.
78 | 6. :demoB
79 | 7. call echo/%%%1%%
80 | 8. goto :EOF
81 |
82 | Inside the function demoB, %1 expands
83 | to str. To read the value contained in str,
84 | it is necessary to enclose
85 | %1 with double percents and instruct the
86 | command interpreter to perform another expansion. This is most easily
87 | accomplished by using the CALL command
88 | as shown in line 7. For a detailed explanation of variable expansion,
89 | see the thread in alt.msdos.batch.nt titled "Variable
90 | expansion (W2KSP2)".
91 | Why would we want to pass arguments like this? Well now
92 | that the function knows the name of a variable, it can assign
93 | it a value and thereby the function can now return values.
94 | Returning Values
95 | So far the contrived examples have only served to illustrate
96 | the points being made. This next example demonstrates how a function
97 | can return a value and is typical of the functions in this library. The
98 | methods used guarantee this function can be inserted, as it stands, into
99 | any batch file without causing any side effects whatsoever.
100 | The function below is called Area and
101 | it simply calculates the product of width and height and then returns
102 | the result. Three arguments are required, the first two should be passed
103 | by value, the third by reference.
104 | [It is a convention of this library to
105 | document a function's arguments by including an argument
106 | list immediately after the function name (as shown below on
107 | line 08). This is a convenient location as anything after the function
108 | name is ignored by the command interpreter. This list serves no other
109 | purpose than to act as a reminder of the type and number of arguments
110 | a function expects.]
111 |
112 | 01. @echo off & setlocal ENABLEEXTENSIONS
113 | 02. set x=2
114 | 03. set y=3
115 | 04. call :Area %x% %y% answer
116 | 05. echo/The area is: %answer%
117 | 06. goto :EOF
118 | 07.
119 | 08. :Area %width% %height% result
120 | 09. setlocal
121 | 10. set /a res=%1*%2
122 | 11. endlocal & set "%3=%res%"
123 | 12. goto :EOF
124 |
125 | Line 04 calls the Area function passing
126 | three arguments (it could equally have read call :Area 2 3 answer).
127 | The first command of the function (line 09) is setlocal.
128 | This command creates a copy of the current environment and this copy
129 | then becomes the
130 | current environment. Line 10 calculates the product of arguments %1 and %2 and
131 | saves the result in the variable called res.
132 | The next line consists of two commands seperated by an ampersand (&).
133 | This causes the command interpreter to expand both commands and then
134 | execute them one after the other. So line 11, after it has been expanded
135 | equates to endlocal & set "answer=6".
136 | Now the endlocal command is executed, which
137 | deletes the copy of the environment created by the most recent setlocal command,
138 | and restores the previous environent. Then set "answer=6" is
139 | executed, and finally on line 12 goto :EOF exits
140 | the function and execution continues at line 05. The net result is that
141 | the Area function has returned a value.
142 | If on line 11, the command
143 | set "%3=%res%", had been
144 | expanded after endlocal had been
145 | executed, then instead of expanding to set "answer=6" it
146 | probably would have been set "answer=" as the
147 | res variable was deleted by the endlocal command.
148 | By Value or Reference
149 | The rule of thumb is to pass arguments by
150 | value unless you need to modify the original values, in which case pass
151 | by reference. The Area function above demonstrates
152 | this rule as the first and second arguments (width and height) are passed
153 | by value, but in order to assign the result of the calculation to the
154 | answer variable, it was passed to the function
155 | by reference.
156 | Sometimes it's necessary to pass arguments by reference even though
157 | read-only access is required. For example, when passing two or more unquoted
158 | arguments where at least one of them contains whitespace, the function
159 | would not be able to determine which argument was which if they had been
160 | passed by value. Calling by reference can also be used to pass arguments
161 | containing so-called 'poison' characters (such as " ! | < > ^ " & %). Protecting
162 | out of Scope Variables
163 | In order to create truely reusable functions, you must ensure that
164 | they do not unintentionally modify variables outside of their own scope.
165 | This is accomplished by enclosing your function's main routine with the
166 | setlocal and endlocal statements as shown in the example above.
167 | Unfortunately things get a little more complicated when two or more
168 | arguments are passed by reference and those arguments need to
169 | be read by your function (as opposed to just being assigned values).
170 | This is best illustrated by the Swap function
171 | shown below.
172 | Protecting Arguments
173 | When passing two or more arguments by reference where those arguments
174 | need to be read, care must
175 | be taken not to destroy any of the arguments before they have all been
176 | read. Consider this example below.
177 |
178 | 01. @echo off & setlocal ENABLEEXTENSIONS
179 | 02. set a=one
180 | 03. set b=two
181 | 04. echo/Before call :swap a b [%a% %b%]
182 | 05. call :Swap a b
183 | 06. echo/After call 1 :swap a b [%a% %b%]
184 | 07. call :Swap b a
185 | 08. echo/After call 2 :swap b a [%a% %b%]
186 | 09.
187 | 10. goto :EOF
188 | 11.
189 | 12. :Swap
190 | 13. setlocal
191 | 14. call set a=%%%1%%
192 | 15. call set b=%%%2%%
193 | 16. endlocal & set "%1=%b%" & set "%2=%a%" & goto
194 | :EOF
195 |
196 |
197 | The above example displays:-
198 |
199 | Before call :swap a b [one two]
200 | After call 1 :swap a b [two one]
201 | After call 2 :swap b a [one one]
202 |
203 | This function is supposed to swap the contents of two variables. Notice
204 | it succeed the first time, but failed on the second. This was caused
205 | by variable names outside of the function clashing with duplicate names
206 | inside the function. Specifically, this is what went wrong:-
207 |
208 | - Line 07 called Swap, the first argument
209 | is b, the second a.
210 | - Line 14 is expanded twice because of the call command,
211 | after the second expansion, the line equates to set a=one,
212 | and once this command is executed, a is
213 | overwritten.
214 | - Line 15 is also expanded twice and equates
215 | to set b=one, in other
216 | words both a and b are
217 | now the one
218 | The usual workaround for this problem is to use variable names that are
219 | unique to your function by preceeding all function variables with the
220 | function name separated by a period. However, if using that approach,
221 | it's actually only necessary to use unique names for vulnerable variables.
222 | Rewriting lines 14-16 of the Area function as shown below would prevent
223 | any arguments being overwritten before they had been saved.
224 |
225 | 14. call set Swap.a=%%%1%%
226 | 15. call set b=%%%2%%
227 | 16. endlocal&set %1=%b%&set %2=%Swap.a%&goto :EOF
228 |
229 |
230 | This method has several drawbacks. Firstly, you must never use a period
231 | in any variable name outside of your functions. Secondly, if the function
232 | doesn't have a really short name and reads a number of variables by reference,
233 | the number of lines of code in the function can double if you want to
234 | avoid 'long' lines of code.
235 | An alternative method is to read the variables with the FOR /F command
236 | using a delimiter character not present in any of the argument values.
237 | Using this method the Swap function could be rewritten as follows:-
238 |
239 | 12. :Swap
240 | 13. setlocal ENABLEEXTENSIONS
241 | 14. for /f "tokens=1-2 delims=¬" %%a in ('echo/%%%1%%¬%%%2%%')
242 | do (
243 | 15. set a=%%a&set b=%%b
244 | 16. )
245 | 17. endlocal&set %1=%b%&set %2=%a%&goto :EOF
246 |
247 | The delimiter character is a '¬' (ASCII 172, which looks like a back-to-front
248 | 'L' on its side). It was chosen because it's rarely used and it appears
249 | on a UK keyboard (above the TAB key). If you don't have this key, you
250 | can type it by holding down the Alt key and typing 172 on the numeric
251 | keypad. The only drawback of this method being your variables must never
252 | contain the delimiter character otherwise you may obtain incorrect results.
253 | This issue was covered in alt.msdos.batch.nt in a thread titled "Function
254 | parameters". |
255 | 
