1\chapter{Options, arguments and path-searching}
2\label{optarg}
3
4\section{Invoking gretl}
5\label{optarg1}
6
7\cmd{gretl} (under MS Windows, \cmd{gretl.exe})\footnote{On Linux,
8  a ``wrapper'' script named \texttt{gretl} is installed.  This script
9  checks whether the \texttt{DISPLAY} environment variable is set; if
10  so, it launches the GUI program, \verb@gretl_x11@, and if not it
11  launches the command-line program, \texttt{gretlcli}}.
12
13--- Opens the program and waits for user input.
14
15\cmd{gretl} \textsl{datafile}
16
17--- Starts the program with the specified datafile in its
18workspace. The data file may be in any of several formats (see the
19\emph{Gretl User's Guide}); the program will try to detect the format
20of the file and treat it appropriately. See also Section
21\ref{path-search} below for path-searching behavior.
22
23\cmd{gretl --help} (or \cmd{gretl -h})
24
25--- Print a brief summary of usage and exit.
26
27\cmd{gretl --version} (or \cmd{gretl -v})
28
29--- Print version identification for the program and exit.
30
31\cmd{gretl --english} (or \cmd{gretl -e})
32
33--- Force use of English instead of translation.
34
35\cmd{gretl --run} \textsl{scriptfile} (or \cmd{gretl -r}
36\textsl{scriptfile})
37
38--- Start the program and open a window displaying the specified
39script file, ready to run.  See Section \ref{path-search} below for
40path-searching behavior.
41
42\cmd{gretl --db} \textsl{database} (or \cmd{gretl -d}
43\textsl{database})
44
45--- Start the program and open a window displaying the specified
46database.  If the database files (the \texttt{.bin} file and its
47accompanying \texttt{.idx} file) are not in the default system
48database directory, you must specify the full path.  See also the
49\emph{Gretl User's Guide} for details on databases.
50
51\cmd{gretl --dump} (or \cmd{gretl -c})
52
53--- Dump the program's configuration information to a plain text file
54(the name of the file is printed on standard output).  May be useful
55for trouble-shooting.
56
57\cmd{gretl --debug} (or \cmd{gretl -g})
58
59--- (MS Windows only) Open a console window to display any messages
60sent to the ``standard output'' or ``standard error'' streams.  Such
61messages are not usually visible on Windows; this may be useful for
62trouble-shooting.
63
64\section{Preferences dialog}
65\label{guiprefs}
66
67Various things in gretl are configurable under the ``Tools,
68Preferences'' menu.  Separate menu items are devoted to the choice of
69the monospaced font to be used in gretl screen output, and, on
70some platforms, the font used for menus and other messages.  The other
71options are organized under five tabs, as follows.
72
73\textbf{General}: Here you can configure the base directory for
74gretl's shared files. In addition there are several check
75boxes. If your native language setting is not English and the local
76decimal point character is not the period (``\texttt{.}''), unchecking
77``Use locale setting for decimal point'' will make gretl use the
78period regardless.  Checking ``Allow shell commands'' makes it
79possible to invoke shell commands in scripts and in the gretl
80console (this facility is disabled by default for security reasons).
81
82\textbf{Programs} tab: You can specify the names or paths to various
83third-party programs that may called by gretl under certain
84conditions.
85
86\textbf{Editor} tab: Set preferences pertaining to the gretl
87script editor.
88
89\textbf{Network} tab: Set the server on which to look for gretl
90databases, and also whether or not you use an HTTP proxy.
91
92\textbf{HCCME} tab: Set preferences regarding robust covariance matrix
93estimation.  See the \emph{Gretl User's Guide} for details.
94
95\textbf{MPI} tab: This is shown only if gretl is built with support
96for MPI (Message Passing Interface).
97
98Settings chosen via the Preferences dialog are stored from one gretl
99session to the next.
100
101\section{Invoking gretlcli}
102\label{optarg2}
103
104\cmd{gretlcli}
105
106--- Opens the program and waits for user input.
107
108\cmd{gretlcli} \textsl{datafile}
109
110--- Starts the program with the specified datafile in its
111workspace. The data file may be in any format supported by gretl
112(see the \emph{Gretl User's Guide} for details). The program will try
113to detect the format of the file and treat it appropriately. See also
114Section \ref{path-search} for path-searching behavior.
115
116\cmd{gretlcli --help} (or \cmd{gretlcli -h})
117
118--- Prints a brief summary of usage.
119
120\cmd{gretlcli --version} (or \cmd{gretlcli -v})
121
122--- Prints version identification for the program.
123
124\cmd{gretlcli --english} (or \cmd{gretlcli -e})
125
126--- Force use of English instead of translation.
127
128\cmd{gretlcli --run} \textsl{scriptfile} (or \cmd{gretlcli -r}
129\textsl{scriptfile})
130
131--- Execute the commands in \textsl{scriptfile} then hand over input
132to the command line.  See Section \ref{path-search} for path-searching
133behavior.
134
135\cmd{gretlcli --batch} \textsl{scriptfile} (or \cmd{gretlcli -b}
136\textsl{scriptfile})
137
138--- Execute the commands in \textsl{scriptfile} then exit.  When using
139this option you will probably want to redirect output to a file. See
140Section \ref{path-search} for path-searching behavior.
141
142When using the \cmd{--run} and \cmd{--batch} options, the script file
143in question must call for a data file to be opened. This can be done
144using the \cmd{open} command within the script.
145
146\section{Path searching}
147\label{path-search}
148
149When the name of a data file or script file is supplied to gretl
150or \app{gretlcli} on the command line, the file is looked for as
151follows:
152
153\begin{enumerate}
154\item ``As is''.  That is, in the current working directory or, if a
155  full path is specified, at the specified location.
156\item In the user's gretl directory (see Table \ref{tab-path} for the
157  default values; note that \texttt{PERSONAL} is a placeholder that is
158  expanded by Windows in a user- and language-specific way, typically
159  involving ``My Documents'' on English-language systems).
160\item In any immediate sub-directory of the user's gretl directory.
161\item In the case of a data file, search continues with the main
162  gretl data directory. In the case of a script file, the search
163  proceeds to the system script directory.  See Table \ref{tab-path}
164  for the default settings.  (\texttt{PREFIX} denotes the base
165  directory chosen at the time gretl is installed.)
166\item In the case of data files the search then proceeds to all
167  immediate sub-directories of the main data directory.
168\end{enumerate}
169
170\begin{table}[htbp]
171  \caption{Default path settings}
172  \label{tab-path}
173  \begin{center}
174    \begin{tabular}{lll}
175       & \textit{Linux} & \textit{MS Windows} \\ [4pt]
176      User directory & \texttt{\$HOME/gretl} &
177        \verb@PERSONAL\gretl@ \\
178      System data directory & \texttt{PREFIX/share/gretl/data} &
179        \verb@PREFIX\gretl\data@ \\
180      System script directory & \texttt{PREFIX/share/gretl/scripts} &
181        \verb@PREFIX\gretl\scripts@ \\
182    \end{tabular}
183  \end{center}
184\end{table}
185
186Thus it is not necessary to specify the full path for a data or script
187file unless you wish to override the automatic searching
188mechanism. (This also applies within \app{gretlcli}, when you supply a
189filename as an argument to the \cmd{open} or \cmd{run} commands.)
190
191When a command script contains an instruction to open a data file, the
192search order for the data file is as stated above, except that the
193directory containing the script is also searched, immediately after
194trying to find the data file ``as is''.
195
196
197\subsection{MS Windows}
198\label{MS-behave}
199
200Under MS Windows configuration information for gretl and
201\app{gretlcli} is stored in the Windows registry. A suitable set of
202registry entries is created when gretl is first installed, and the
203settings can be changed under gretl's ``Tools, Preferences'' menu. In
204case anyone needs to make manual adjustments to this information, the
205entries can be found (using the standard Windows program
206\app{regedit.exe}) under \verb@Software\gretl@ in
207\verb@HKEY_LOCAL_MACHINE@ (the main gretl directory and the paths to
208various auxiliary programs) and \verb@HKEY_CURRENT_USER@ (all other
209configurable variables).
210
211