The INCLUDE command inserts files named in its argument list into the program text in place of the INCLUDE command. INCLUDE files should contain Statistics101 commands, usually subroutines (see NEWCMD) and/or constant definitions (see NAME, COPY, and GLOBAL). The result is that a new expanded program is created temporarily by Statistics101 that is the original file with each of its INCLUDE statements replaced by the contents of all the files listed in its argument list. The full program with all the nested included files expanded can be viewed and debugged in the Debug Window tab of the Program Panel.
The INCLUDE command takes one or more file names as arguments. Each file name must be enclosed between double quotes. There must be at least one space between adjacent file names.
Nested directories (such as "C:/dir1/dir2/myFile") should be delimited by "/" or by "\\" characters. The reason for the double backslash is that in Java as in other C-derived languages, a backslash is interpreted as an escape character and two backslashes are interpreted as a single true backslash. This is true whether using Statistics101 in Windows, Unix, Linux, or MacOS. The forward slash will work on any operating system, so you might prefer to use it.
The fileName arguments may be absolute or relative. An absolute file name is the entire directory path to the file. For example, "C:/Program Files (x86)/Statistics101_2.7/lib/PERTcommands.txt" is an absolute file path name.
A relative file name is a partial path name. A relative file name will be interpreted relative to the Statistics101 working directory, which in Microsoft Windows 7 is usually "C:/Program Files (x86)/Statistics101". For example if you had this INCLUDE command with this relative file name:
the file would be interepreted as "C:/Program Files (x86)\Statistics101_2.7/lib/PERTcommands.txt". Relative file names can be used for any of the files in Statistics101's /lib directory.
To make for easier access to any INCLUDE files you create, it is suggested that you put them all in a single directory. Statistics101 creates a default a directory named, "ResamplingStatsSubroutines" that is in your user directory. Then you could include library files needed by your programs like this (you can't use relative paths for files in this library since they are not in Statistics101's working directory):
You can put INCLUDE commands anywhere in your program as long as the rules for variable, constant, and subroutine definitions are followed. That is, constants, subroutines and input variables must be defined in the text before they are used in the text.
Included files may also contain INCLUDE commands to any number of levels. Recursive INCLUDEs are not allowed. For example, if file A INCLUDEs file B which INCLUDEs file A, that will generate an error message and the program will not be executed.
If an INCLUDE file has already been included and another INCLUDE command is encountered to include the same file, the file will not be included again. This avoids doubly defining constants, variables, and subroutines in cases such as when a program file includes two other files that both include a common library file(s).
Statistics101 has the ability to insert missing INCLUDE commands if subroutines invoked in your program can be found in the "lib" directory or, optionally, in the "ResamplingStatsSubroutines" directory or whatever directory you specified for your subroutines in the Preferences dialog's "General" tab (Edit>Preferences...). This is called the auto-INCLUDE feature. It works like this: say you are writing a program and you need to compute a factorial, so you invoke the FACTORIAL subroutine. That subroutine is in the "mathCommands.txt" file in the "lib" directory. Therefore your program needs an INCLUDE command naming that file so Statistics101 can find the subroutine. If you don't type in the INCLUDE command yourself, then when you run a syntax check or run the program, Statistics101 will insert the needed INCLUDE command automatically.
The auto-INCLUDE feature is controlled by options in the Editor tab of the "Preferences" dialog. The "Preferences" dialog is available via the menu Edit>Preferences....
Assume that a file named "c:/mathFunctions.txt" contains the definitions for a number of math subroutines such as the following:
'contents of file "C:/mathFunctions.txt": NAME 3.141592653589793 pi GLOBAL pi 'Subroutine to compute the area of a circle NEWCMD CIRCAREA radius area SQUARE radius radiusSquared MULTIPLY radiusSquared pi area END ' . . . more subroutines, not shown 'End of file "C:/mathFunctions.txt"
Now you could write your own program that uses such predefined subroutines as follows:
'Main program using the subroutine from the file:
INCLUDE "c:/mathFunctions.txt" COPY 1,10 Radii CIRCAREA Radii Areas '<== Uses subroutine from included file PRINT TABLE radii areas
You can include several files with one INCLUDE command as long as all the file names are on the same line as the INCLUDE command:
INCLUDE "lib/mathFunctions.txt" "lib/probabilityFunctions.txt" "lib/cardDeckDefinitions.txt"
Or, you can include several files each with its own INCLUDE command:
INCLUDE "lib/mathFunctions.txt" INCLUDE "lib/probabilityFunctions.txt" INCLUDE "lib/cardDeckDefinitions.txt"