.. index::
   single: Command Files
   single: Add Files
   single: Groups
   single: Do Loops
   single: G7 Command; add
   single: G7 Command; fadd
   single: G7 Command; pause
   single: G7 Command; catch
   single: G7 Command; addprint
   single: G7 Command; addpause
   single: G7 Command; function
   single: Nested Loops

   
Command Files, Groups, and Do Loops
===================================

Files containing *G7* commands can be prepared with a text editor and then introduced to the program by the command 

**add <filename> [Arguments]**

The commands in the named file then will be executed as if they were being typed in at the keyboard. Add files can contain *add* commands.  Add files can "add" themselves.  They commonly are used to introduce data, to set up complicated regressions, and to supplement *G7*'s functions.  The arguments are optional in an *add* command. 


**Arguments in Add Files**

Add files may have up to 99 arguments.  Consider the problem of calculating the percentage change of a quarterly series over the 3-quarter moving average of the series a year earlier.  If x is the original series, this growth rate, grx, could be computed by ::

   f ma   = (x + x[1] + x[2])/3
   f grx  = (x - ma[3])/ma[3]

Those are fairly long formulas, so if you had to do this calculation for many different series, you would find it advantageous to make up a file with a short name like AGR.ADD (for annual growth rate) as follows::

  f ma   = (%1 + %1[1] + %1[2])/3
  f gr%1 = (%1 - ma[3])/ma[3]

You would use it like this::

   add AGR.ADD x

The effect will be exactly as if the original pair of lines had been executed.  Every occurrence of %1 will be replaced by the variable 'x'.  You now can calculate the growth rate of any variable; if the name of the variable were n37z2y, the command would be ::

   add AGR.ADD n37z2y

and the variable grn37z2y would be created.  

Up to nine arguments may be used.  Here is an example with two. In the example, investment of sector 32 depends on imports of sector 57 in a regression equation.

Make the file INVEST.REG as follows::

   f d%1   = out%1 - out%1[1]
   r inv%1 = out%1, d%1[1], d%1[2], rtb, rep%1, import%2 

The command "add invest.reg 32 57" will execute these *f* and *r* commands replacing all occurrences of %1 with 32 and all occurences of %2 by 57.  What would be executed would be ::

   f d32   = out32 - out32[1]
   r inv32 = out32, d32[1], d32[2], rtb, rep32, import57 

Arguments are useful for estimating a similar equation form for different industries, states, or other entities.

An argument may be a text string enclosed in double quotation marks (").  Example: Let the file OUTEXP be ::

   ti %1 %2
   gr out%1 exp%1

then :: 

   add outexp 17 "Printing and Publishing"

would have the same effect as ::

   ti 17 Printing and Publishing
   gr out17 exp17

The last line of the configuration file for *G7*, G.CFG, may contain an *add* command.  A typical example might be::

   Initial add command; add INITIAL.ADD

Such a file typically might be used to select a printer or specify screen or graphics options.


**Groups and Group Arguments in Add commands**

A special type of argument is a group. The concept "group" comes from multi-sectoral modelling where sector variables have names such as out1, out2, ..., out85.  A group is a set of specific sector numbers.  For example, all industries include sectors 1-85; non-durable industries include sectors 5-13, and durable industries include sectors 14-24, and so on.  Here we have three groups of sector numbers: 1-85, 5-13, and 14-24.  To use a group as an argument, we must enclose those sectors in parentheses like this::

   (1-85), (5-13), and (14-24)

Groups also may specify sets of spreadsheet columns.  For example, to construct a group of the first 30 columns of a spreadsheet, the group should be ::

   (A-AD)

Groups also may be specified as named or dynamic groups.  For example, to construct a group of all non-chemical manufacturing sectors, where manufacturing and chemical sectors are defined as ::

   group Manufacturing
      1-58
   group Chemicals
      20-27

then a group to include all manufacturing sectors except chemicals may be specified as ::

   ( :Manufacturing ( :Chemicals ))

This is equivalent to ::

   ( 1-58 ( 20-27 ) )

Note finally that these various specifications may be combined.  For example, the following is another alternative to the example above::

   ( :Manufacturing ( 20-27 ) )

An *add* command allows its last nine arguments to be groups. Take the earlier example of calculating the percentage change of a series over a 3-quarter moving average. Suppose we have 85 quarterly output series: out1 through out85.  We may modify the AGR.ADD file in the earlier example to become the following::

   f ma     = (%1%2 + %1%2[1] + %1%2[2])/3
   f gr%1%2 = (%1%2 - ma[3])/ma[3]

we then could write out 85 add commands as follows::

   add AGR.ADD out 1
   add AGR.ADD out 2
   add AGR.ADD out 85

Equivalently, we can write them out in only one add command::

   add AGR.ADD out (1-85)

In this example, the variable ma acts like a temporary variable, and 85 new series, grout1 through grout85, are created in the workspace.  If we similarly want to compute the moving average series for another variable, such as industry sales, sale1 through sale55, we may use the command::

   add AGR.ADD sale (1-55)

Again, up to nine group arguments are allowed.  However, group arguments must come at the end of the argument list.  If two group arguments are used, by default, the outer loop is controlled by the first group argument, and the inner loop by the second group argument.  For example, ::

   add INVEST.REG (32-34) (52-54)

is equivalent to ::

   add INVEST.REG 32 (52-54)
   add INVEST.REG 33 (52-54)
   add INVEST.REG 34 (52-54)

There is an alternative to the double loop, parallel matching, with an 'm' option after the second group. For example, ::

   add INVEST.REG (32-34) (52-55(53)) m

is equivalent to ::

   add INVEST.REG 32 52
   add INVEST.REG 33 54
   add INVEST.REG 34 55

That is, the first members of each group are matched to be the first pair of arguments, the second member of each group to be the second pair, and so on.  Loops with parallel matching may contain only two groups.  The two groups must have equal number of members in parallel matching.


**Loop with Do Command**

A *do* command allows you to run a set of *G7* commands like an *add* command without creating the add file.  Its format is

**do{ <G7 commands with variables> }[Arguments]**
   where variables are %1, %2, etc., just as in an add file.  A *do* command can continue on several lines.  However, the arguments should be placed on the same line as the closing brace '}'.  As with the *add* command, no more than 9 arguments are allowed, and the last several arguments may be groups.  In fact, the last nine arguments may be groups.  
      
   For example, the AGR.ADD example can be rewritten with a do command like this::

      do{f ma     = (%1%2 + %1%2[1] + %1%2[2])/3   
         f gr%1%2 = (%1%2 - ma[3])/ma[3]
         } out (1-85)

   In this case, however, the file AGR.ADD need not be created.  A *do* command thus provides an easy way to have a loop.

   Nesting of *do* loops is possible.  A loop may be nested within an add file or within another do loop.  For example, the following code computes the sums of the rows of matrix 'X'.  The values are stored in vector rowsum.  Note that an argument is passed from the outer loop to the inner loop.  This is accomplished by using a variable from the outer loop to specify a group for the inner loop. ::

      do{f sum = 0   
        do{f sum = sum + X%2.%1
          }(%1) (1-5)      
        vf rowsum%1 = sum
        }(1-5)

    
**Command File with an Argument File**

**fadd <CommandFile> <ArgumentFile> [<arg> [<arg>] ...]**
   The named CommandFile is first executed with the arguments from the first line of named ArgumentFile, then the CommandFile is executed again with the arguments from the second line of the ArgumentFile, and so on until the ArgumentFile is exhausted.  Additional arguments may be supplied with the *fadd* command, and these will be added to each line of arguments provided in the arguments file.  
      
   For example, the CommandFile might be ::

      ti %2
      gr %1

   while the ArgumentFile was ::

      gnp$    "Gross National Product"
      vfnre$  "Investment in producer durable equipment"
      vfnrs$  "Investment in non-residential structures"

   Then the result would be three properly titled graphs.  


.. _G7UGUserFunctions:

**User-defined Functions**
 
| **function <function name> { <G7 commands with variables> }**
| **function clear [<name>]**
|    *G7* allows the user to define functions so that similar operations can be repeated easily.  This feature is very similar to the *add* command described above, but it allows the entire script to be specified in a single file.  Once a function is defined, it may be used repeatedly.  *function clear* will remove all defined functions, or if a function name is specified, then that function will be removed.

   Functions may contain arguments; see the description of the *add* command for details.  A good practice is to specify function names that contains at least one capital letter.  This will avoid confusion between the user's functions and *G7* commands and keywords.  Once it is defined, a function may be called by entering the function name in the same manner as other *G7* commands.  If arguments are to be passed to the function, they should be listed after the function name.  

   Note that the *addtype* setting automatically is set to "no" within each function, so that the function contents are not printed to screen during processing.  For debugging purposes, *addtype* commands can be given within the function to override this practice.

   *G7* supports recursive techniques.  For example, the function command may be employed to construct a Fibonacci sequence.  The only restrictions for this sequence are the inherent limits of the 32-bit software, but even so, up to 47 iterations are possible before the limit is reached.

   The following code repeats the example above while employing the function command. ::

      function GR{      
         ti %2
         gr %1
         }     
      GR gnp$    "Gross National Product"
      GR vfnre$  "Investment in producer durable equipment"
      GR vfnrs$  "Investment in non-residential structures"
     
**function list**
   This routine will print a list of names of the user-defined functions.  

**function print [<function_name>]**
   This routine will print the specification of the function function_name.  If no name is provided, then the specification of every function will be printed.  

   
**Other Commands That Are Useful in Add Files**

| **(addt)ype <n | y>**
| **(addpr)int**
|    Invoked with an 'n' for "no", this command turns off the typing on the screen of the contents of the "add" files.  This speeds up the processing of large data files.  Turn printing back on with "addtype y" for "yes".  This command is also known as *(addp)rint*.

**catch <file_name>**
   Captures screen displays (except graphs) to the named file.  Use to capture the setup of a regression and its results into a single file.  A regression display is caught as it stands when you proceed to the next command.  To turn off the catching type "catch off"

**Commenting Add Files**

Add files are like small computer programs, and should be commented.  A line beginning with a pound sign, '#', is treated as a comment.  A line beginning ith a colon, ':', causes that line and all subsequent lines to be treated as a comment until a line beginning with a colon again is encountered. (The line of the second colon is also a comment.)

Examples::

   # This is a one line comment.
   : This comment, however, is longer.
   Clearly, it is a much more important comment,
   for it takes three lines.
   : Or four.

**Pausing to View Output in Results Window**

If you have a very long add file, the results may all rush by before you have a chance to examine them.  There are a number of ways to solve this problem.  The simplest is just to scroll the results window up to examine the output that has flashed before you.  A second is to use the catch command to capture most of the output to a file, where it can then be examined with the editor.  Occasionally it is convenient to just pause the operation of the add file for a moment.  One way to do this is with the *pause* command.  Just include the command *pause* on a single line in your add file, and *G7* will stop when it reaches that point, and display a message box on the screen.  At this point, hit an 'ESC' to stop the addfile or any other key to continue.

**pause [<"message">]**
   The *pause* command causes *G7* to pause, optionally print a message, and prompt the user to continue or to cancel the process.  Note that if more than one word is to be included, the message must be surrounded by quotes.

Another way to pause is to use the *addpause* command:

**addpause < y | n>**
   This command cause *G7* to pause just before the beginning of each add file and to display a message box.  This pause feature also allows you to hit an 'ESC', or click on the 'ESC' button to stop the add file sequence.