CALL

Call one batch program from another.

Syntax
      CALL [drive:][path]filename [parameters]

      CALL :label [parameters]

      CALL internal_cmd

Key:
   parameters   Any command-line arguments.

   :label       Jump to a label somewhere within the
                current batch file.

   internal_cmd Any internal NT command
                CALLing a command in this way (rather 
                than simply running it) will evaluate
                any environment variable parameters

note: CALL does support network (UNC) pathnames

Passing Parameters

When calling a secondary batch file or subroutine, you will often want the routine to manipulate some data, the data (usually a variable) should be passed as a parameter.

Jumping to a label

A label is defined by a single colon followed by a name

As this is effectively a subroutine I always prefix the name with s_
e.g.
:s_error_trap

When you jump to a subroutine with CALL, all statements after the label are executed until either the end of the script is reached, or a GOTO :eof command.

GOTO :eof will return back to just after the position where you used CALL.

Don't forget you can also pass command line arguments to the :label and refer to these just like the parameters passed to a separate batch file.

For example

   @ECHO OFF
   SETLOCAL
   CALL :s_staff SMITH 100
   GOTO s_last_bit

   :s_staff
   ECHO Name is %1
   ECHO Rate is %2
   GOTO :eof

   :s_last_bit
   ECHO The end of the script
   

Returning Parameters

When a subroutine contains local variables (SETLOCAL) you will need a method of returning values, i.e. setting a variable that is passed back to the calling routine.

This is done by executing the ENDLOCAL command on the same line as a SET statement(s)

For example

   @ECHO OFF
   SETLOCAL
   CALL :s_calc 200 100
   ECHO %v_return%
   GOTO :eof

   :s_calc
   SETLOCAL
   SET v_sum=0
   IF %1 GTR %2 SET v_sum=5 
   ENDLOCAL & SET v_return=%v_sum%
   GOTO :eof

The use of SETLOCAL and ENDLOCAL is roughly equivalent to option explicit in Visual Basic, it's use is strongly recommended.

You should also use SETLOCAL and ENDLOCAL when passing values from one batch file to another.

Advanced usage : CALLing internal commands

As well as running a subroutine, CALL can also be used to run any internal command (SET, ECHO etc) and cruicially will evaluate any environment variables passed on the same line.

Each CALL does one substitution of the variables. (You can also do CALL CALL... for multiple substitutions)

For example

   @ECHO off
   SETLOCAL
   set pc1=frodo3
   set pc2=gandalf4
   set pc3=ascom5
   set pc4=qwerty2
   set pc5=last1
   
   ::Loop through all the PCs
   FOR /L %%n IN (1,1,5) DO (call :loop %%n)
   goto :s_next_bit
   
   :loop
   set v_pc_name=pc%1
   :: Evaluate the PC's name
   CALL SET v_pc_name=%%%v_pc_name%%%
   echo The pc is %v_pc_name%
   goto :eof
   
   :s_next_bit
   :: continue below

:: Notice that to evaluate the contents of %pc1%
:: requires triple '%' symbols i.e CALL SET v_pc_name=%%%v_pc_name%%%

If Command Extensions are disabled, the CALL command will not accept batch labels.

"My mother never saw the irony in calling me a son-of-a-bitch." - Jack Nicholson

Related commands:

CMD - can be used to call a subsequent batch and ALWAYS return even if errors occur.
GOTO - jump to a label or GOTO :eof
START - Start a separate window to run a specified program or command

Equivalent Linux BASH commands:

. (dot operator) - Include (run) commands from another file
builtin - Run a shell builtin
chroot - Run a command with a different root directory