How parameter inclusion works

Batinclude passes user defined arguments into selected places within the included file.  Argument1, argument2,.. are arguments passed for substitution.  These arguments can be single unbroken strings (quoted or unquoted) or quoted multi-part strings that include spaces and special characters.

The arguments are treated as character strings that are substituted by argument number inside the included file as in the DOS batch facility.  Argument substitution is indicated by using the character % followed immediately by the argument number where %1 refers to the first argument, %2 to the second argument, and so on.

Names may be used for the substitutable parameters using the procedure discussed under the $setargs command.

Example:

Suppose we wish to do addition involving different elements in fact suppose we have scalars a and b with data and wish to form

c = a + b;

d = a + c;

We can accomplish this with a Batinclude file.  In particular, we can write a file that sets

Argument1 = argument2 + argument3

and call it twice

once with arguments c , a , b

again with arguments d , a , c

To do this we build a file that contains

%1 = %2 + %3 ;

and call it batincadd.gms.

Then we build addbat.gms which will include the above file twice using the syntax

scalar a /2/, b /4/, c ,d  ;

$Batinclude batincadd c a b

$Batinclude batincadd d a c

In turn the LST file from the run shows the following

   1  *main program for Batinclude example

   2  scalar a /2/, b /4/, c ,d  ;

BATINCLUDE C:\GAMS\GAMSPDF\BIGONE\BATINCADD.GMS

   4  *example of arguments in Batinclude

   5  c = a + b;

BATINCLUDE C:\GAMS\GAMSPDF\BIGONE\BATINCADD.GMS

   7  *example of arguments in Batinclude

   8  d = a + c;

Note in line 2 of the source the statement

$Batinclude batincadd c a b

has three arguments ( c a b ) attached to the call of the included file batincadd.gms and that this causes a substitution of the parameters into

%1 = %2 + %3 ;

 a is the second argument and goes into place %2

 b is the third argument and goes into place %3

yielding

c = a + b;

in line 3 of the LST file.

The equivalent example using setargs is in setargs.gms and batincsag.gms which causes the Batinclude file to use number1 in place of %1, second in place of %2 , house in place of %3 and * for all remaining using code like

$setargs number1 second house *

%number1% = %second% * %house%;

in the BATINCLUDE instead of

%1=%2*%3;

Note setargs must appear in the Batincluded file.  Also note that the * or a . or a / will cause a numbered item to be skipped over.

Notes:

Additional Examples:

The full power of a include with arguments can best be appreciated by expanding the example

Adding the line below to addbat.gms

$Batinclude batincadd d "a+b-d*a" "c*sqrt(abs(a+1))"

results in an LST file with

10  d = a+b-d*a c*sqrt(abs(a+1));

showing that quoted items for arguments can result in substitution of formulae in the included file.

Adding a fourth argument to activation of the Batinclude file (addbat.gms) in a slightly different file batincadd2.gms

$Batinclude batincadd2 d a c "text for the display"

and adding the line to the included file

display "%4", "%0"

yields the LST file component

display "text for the display", "C:\GAMS\GAMSPDF\BIGONE\BATINCADD2.GMS"

and the display output

----     16 text for the display

            D:\GAMSPDF\BATINCADD2.GMS

More complex examples also appear in the conditional compilation chapter.

Note the parameter %0 gives the name of the file being incorporated by the Batinclude.