\chapter{Options, arguments and path-searching} \label{optarg} \section{Invoking gretl} \label{optarg1} \cmd{gretl} (under MS Windows, \cmd{gretlw32.exe})\footnote{On Linux, a ``wrapper'' script named \texttt{gretl} is installed. This script checks whether the \texttt{DISPLAY} environment variable is set; if so, it launches the GUI program, \verb@gretl_x11@, and if not it launches the command-line program, \texttt{gretlcli}}. --- Opens the program and waits for user input. \cmd{gretl} \textsl{datafile} --- Starts the program with the specified datafile in its workspace. The data file may be in any of several formats (see the \emph{Gretl User's Guide}); the program will try to detect the format of the file and treat it appropriately. See also Section \ref{path-search} below for path-searching behavior. \cmd{gretl --help} (or \cmd{gretl -h}) --- Print a brief summary of usage and exit. \cmd{gretl --version} (or \cmd{gretl -v}) --- Print version identification for the program and exit. \cmd{gretl --english} (or \cmd{gretl -e}) --- Force use of English instead of translation. \cmd{gretl --run} \textsl{scriptfile} (or \cmd{gretl -r} \textsl{scriptfile}) --- Start the program and open a window displaying the specified script file, ready to run. See Section \ref{path-search} below for path-searching behavior. \cmd{gretl --db} \textsl{database} (or \cmd{gretl -d} \textsl{database}) --- Start the program and open a window displaying the specified database. If the database files (the \texttt{.bin} file and its accompanying \texttt{.idx} file) are not in the default system database directory, you must specify the full path. See also the \emph{Gretl User's Guide} for details on databases. \cmd{gretl --dump} (or \cmd{gretl -c}) --- Dump the program's configuration information to a plain text file (the name of the file is printed on standard output). May be useful for trouble-shooting. \cmd{gretlw32 --debug} (or \cmd{gretlw32 -g}) --- (MS Windows only) Open a console window to display any messages sent to the ``standard output'' or ``standard error'' streams. Such messages are not usually visible on Windows; this may be useful for trouble-shooting. \section{Preferences dialog} \label{guiprefs} Various things in \app{gretl} are configurable under the ``Tools, Preferences'' menu. Separate menu items are devoted to the choice of the monospaced font to be used in \app{gretl} screen output, and, on some platforms, the font used for menus and other messages. The other options are organized under five tabs, as follows. \textbf{General}: Here you can configure the base directory for \app{gretl}'s shared files. In addition there are several check boxes. Checking ``Tell me about gretl updates'' makes \app{gretl} attempt to query the update server at start-up. If your native language setting is not English and the local decimal point character is not the period (``\texttt{.}''), unchecking ``Use locale setting for decimal point'' will make \app{gretl} use the period regardless. Checking ``Allow shell commands'' makes it possible to invoke shell commands in scripts and in the \app{gretl} console (this facility is disabled by default for security reasons). \textbf{Databases} tab: You can select the directory in which to start looking for native \app{gretl} databases; the directory in which to start looking for RATS 4 databases; the host name of the \app{gretl} database server to access; and the IP number and port number of the HTTP proxy server to use when contacting the database server (if you're behind a firewall). \textbf{Programs} tab: You can specify the names or paths to various third-party programs that may called by \app{gretl} under certain conditions. Note that the item ``Command to compile {\TeX} files'' can be set to either latex or pdflatex; if latex is selected, {\TeX} output will be previewed in DVI format; if pdflatex is selected, the preview will be in PDF format. \textbf{HCCME} tab: Set preferences regarding robust covariance matrix estimation. See the \emph{Gretl User's Guide} for details. \textbf{Manuals} tab: Select your preferred language for the full \app{gretl} documentation in PDF format (currently only English and Italian are supported). When using the English documentation you can also choose between US letter paper and A4 paper. Settings chosen via the Preferences dialog are stored from one gretl session to the next. Under MS Windows they are stored in the Windows registry; on other platforms they are stored in a plain text file named \texttt{.gretl2rc} in the user's home directory. \section{Invoking gretlcli} \label{optarg2} \cmd{gretlcli} --- Opens the program and waits for user input. \cmd{gretlcli} \textsl{datafile} --- Starts the program with the specified datafile in its workspace. The data file may be in any format supported by \app{gretl} (see the \emph{Gretl User's Guide} for details). The program will try to detect the format of the file and treat it appropriately. See also Section \ref{path-search} for path-searching behavior. \cmd{gretlcli --help} (or \cmd{gretlcli -h}) --- Prints a brief summary of usage. \cmd{gretlcli --version} (or \cmd{gretlcli -v}) --- Prints version identification for the program. \cmd{gretlcli --english} (or \cmd{gretlcli -e}) --- Force use of English instead of translation. \cmd{gretlcli --run} \textsl{scriptfile} (or \cmd{gretlcli -r} \textsl{scriptfile}) --- Execute the commands in \textsl{scriptfile} then hand over input to the command line. See Section \ref{path-search} for path-searching behavior. \cmd{gretlcli --batch} \textsl{scriptfile} (or \cmd{gretlcli -b} \textsl{scriptfile}) --- Execute the commands in \textsl{scriptfile} then exit. When using this option you will probably want to redirect output to a file. See Section \ref{path-search} for path-searching behavior. When using the \cmd{--run} and \cmd{--batch} options, the script file in question must call for a data file to be opened. This can be done using the \cmd{open} command within the script. \section{Path searching} \label{path-search} When the name of a data file or script file is supplied to \app{gretl} or \app{gretlcli} on the command line, the file is looked for as follows: \begin{enumerate} \item ``As is''. That is, in the current working directory or, if a full path is specified, at the specified location. \item In the user's gretl directory (see Table \ref{tab-path} for the default values; note that \texttt{PERSONAL} is a placeholder that is expanded by Windows in a user- and language-specific way, typically involving ``My Documents'' on English-language systems). \item In any immediate sub-directory of the user's gretl directory. \item In the case of a data file, search continues with the main \app{gretl} data directory. In the case of a script file, the search proceeds to the system script directory. See Table \ref{tab-path} for the default settings. (\texttt{PREFIX} denotes the base directory chosen at the time \app{gretl} is installed.) \item In the case of data files the search then proceeds to all immediate sub-directories of the main data directory. \end{enumerate} \begin{table}[htbp] \caption{Default path settings} \label{tab-path} \begin{center} \begin{tabular}{lll} \textit{ } & \textit{Linux} & \textit{MS Windows} \\ [4pt] User directory & \texttt{\$HOME/gretl} & \verb@PERSONAL\gretl@ \\ System data directory & \texttt{PREFIX/share/gretl/data} & \verb@PREFIX\gretl\data@ \\ System script directory & \texttt{PREFIX/share/gretl/scripts} & \verb@PREFIX\gretl\scripts@ \\ \end{tabular} \end{center} \end{table} Thus it is not necessary to specify the full path for a data or script file unless you wish to override the automatic searching mechanism. (This also applies within \app{gretlcli}, when you supply a filename as an argument to the \cmd{open} or \cmd{run} commands.) When a command script contains an instruction to open a data file, the search order for the data file is as stated above, except that the directory containing the script is also searched, immediately after trying to find the data file ``as is''. \subsection{MS Windows} \label{MS-behave} Under MS Windows configuration information for \app{gretl} and \app{gretlcli} is stored in the Windows registry. A suitable set of registry entries is created when \app{gretl} is first installed, and the settings can be changed under \app{gretl}'s ``Tools, Preferences'' menu. In case anyone needs to make manual adjustments to this information, the entries can be found (using the standard Windows program \app{regedit.exe}) under \verb@Software\gretl@ in \verb@HKEY_LOCAL_MACHINE@ (the main \app{gretl} directory and the paths to various auxiliary programs) and \verb@HKEY_CURRENT_USER@ (all other configurable variables).