2.1 The Mapi Client Utility

The mclient program is the universal command-line tool that implements the MAPI protocol for client-server interaction with MonetDB.

On a Windows platform it can be started using start->MonetDB->MonetDB SQL Client. Alternatively, you can use the command window to start mclient.exe. Be aware that your environment variables are properly set to find the libraries of interest.

On a Linux platform it provides readline functionality, which greatly improves user interaction. A history can be maintained to ease interaction over multiple sessions.

A mclient requires minimally a language and host or port argument. The default setting is geared at establishing a guest connection to a SQL or XQuery database at a default server running on the localhost. The -h hostname specifies on which machine the MonetDB server is running. If you communicate with a MonetDB server on the same machine, it can be omitted.

The timer switch reports on the round-about time for queries sent to the server. It provides a first impression on the execution cost.

     Usage: mclient --language=(sql|xquery|mal|mil) [ options ]
     
     Options are:
      -d database | --database=database  database to connect to
      -e          | --echo             echo the query
      -f kind     | --format=kind      specify output format {dm,xml} for XQuery, or {csv,tab,raw,sql,xml}
      -H          | --history          load/save cmdline history (default off)
      -h hostname | --host=hostname    host to connect to
      -i          | --interactive      read stdin after command line args
      -l language | --language=lang    {sql,xquery,mal,mil}
      -L logfile  | --log=logfile      save client/server interaction
      -P passwd   | --passwd=passwd    password
      -p portnr   | --port=portnr      port to connect to
      -s stmt     | --statement=stmt   run single statement
      -t          | --time             time commands
      -X          | --Xdebug           trace mapi network interaction
      -u user     | --user=user        user id
      -?          | --help             show this usage message
      -| cmd      | --pager=cmd        for pagination
     
     SQL specific opions 
      -r nr       | --rows=nr          for pagination
      -w nr       | --width=nr         for pagination
      -D          | --dump             create an SQL dump
     
     XQuery specific options
      -C colname  | --collection=name  collection name
      -I docname  | --input=docname    document name, XML document on standard input

The default mapi_port TCP port used is 50000. If this port happens to be in use on the server machine (which generally is only the case if you run two MonetDB servers on it), you will have to use the -p port do define the port in which the mserver is listening. Otherwise, it may also be omitted. If there are more than one mserver running you must also specify the database name -d database. In this case, if your port is set to the wrong database, the connection will be always redirect to the correct one. Note that the default port (and other default options) can be set in the server configuration file.

Within the context of each query language there are more options. They can be shown usin the command \? or using the commandline.

For SQL there are several knobs to tune for a better rendering of result tables (\w).

     shell> mclient -lsql --help
     \?      - show this message
     \<file  - read input from file
     \>file  - save response in file, or stdout if no file is given
     \|cmd   - pipe result to process, or stop when no command is given
     \h      - show the readline history
     \t      - toggle timer
     \e      - echo the query in sql formatting mode
     \D table- dumps the table, or the complete database if none given.
     \d table- describe the table, or the complete database if none given.
     \A      - enable auto commit
     \a      - disable auto commit
     \f      - format using a built-in renderer {csv,tab,raw,sql,xml} 
     \w#     - set maximal page width (-1=raw,0=no limit, >0 max char)
     \r#     - set maximum rows per page (-1=raw)
     \L file - save client/server interaction
     \X      - trace mclient code
     \q      - terminate session