\chapter{Options, arguments and path-searching}
\label{optarg}

\section{Invoking gretl}
\label{optarg1}

\cmd{gretl} (under MS Windows, \cmd{gretl.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{gretl --debug} (or \cmd{gretl -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 gretl are configurable under the ``Tools,
Preferences'' menu.  Separate menu items are devoted to the choice of
the monospaced font to be used in 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
gretl's shared files. In addition there are several check
boxes. 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 gretl use the
period regardless.  Checking ``Allow shell commands'' makes it
possible to invoke shell commands in scripts and in the gretl
console (this facility is disabled by default for security reasons).
      
\textbf{Programs} tab: You can specify the names or paths to various
third-party programs that may called by gretl under certain
conditions.

\textbf{Editor} tab: Set preferences pertaining to the gretl
script editor.

\textbf{Network} tab: Set the server on which to look for gretl
databases, and also whether or not you use an HTTP proxy.
      
\textbf{HCCME} tab: Set preferences regarding robust covariance matrix
estimation.  See the \emph{Gretl User's Guide} for details.
      
\textbf{MPI} tab: This is shown only if gretl is built with support
for MPI (Message Passing Interface).
      
Settings chosen via the Preferences dialog are stored from one gretl
session to the next.
      
\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 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 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
  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 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{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 gretl and
\app{gretlcli} is stored in the Windows registry. A suitable set of
registry entries is created when gretl is first installed, and the
settings can be changed under 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 gretl directory and the paths to
various auxiliary programs) and \verb@HKEY_CURRENT_USER@ (all other
configurable variables).

