.\" XXX standard disclaimer belongs here....
.\" $Header: RCS/monitor,v 1.9 91/08/15 18:51:58 kemnitz Exp $
.SP MONITOR UNIX 6/14/90
.XA 1 "Terminal Monitor"
.uh NAME
.lp
monitor \*- run the interactive terminal monitor
.uh SYNOPSIS
.lp
.b monitor
[-h hostname] [-p port] [-t tty_device] [-N] [-A] [-c query] [-d path] [-q]
[-o options] 
dbname
.uh DESCRIPTION
.lp
The interactive terminal monitor is a simple frontend to \*(PP.
It enables one to formulate, edit and review queries before
issuing them to \*(PP.
If changes must be made,
a \*(UU editor may be called
called to edit the
.b "query buffer" ,
which the terminal monitor manages.
The editor used is determined by the value of
the
.A EDITOR
environment variable.
If
.A EDITOR
is not set, then
.b vi
is used by default.
.sp
The terminal monitor requires that the postmaster be running, and the ports
(specified with the "-p" option or by the PGPORT environment variable)
must be identical to those specified to the postmaster.
.uh "COMMAND OPTIONS"
.lp
\fI-h host\fR specifies host machine on which the POSTGRES backend
is running; default is your local machine (localhost).
.sp
\fI-p port\fR specifies the well known TCP/IP port used for network 
communication between the terminal monitor and the postmaster.
.sp
\fI-t tty_device\fR specifies the path name to the tty device (or regular
UNIX file) tty which you want the backend debugging messages to be sent to;
default is /dev/null. 
\fI-N\fR specifies that query results will be dumped to the screen without
any attempt at formatting.  This is useful in conjunction with the
.b -c
option in shell scripts.
.sp
\fI-A\fR specifies that attribute names will not be printed - only the
data itself.  This is useful in conjunction with the 
.b -c
option in shell scripts.
.sp
\fI-c query\fR specifies that the monitor is to run one query and exit.
This is useful for shell scripts, typically in conjunction with the
.b -N
and
.b -A
options.  Examples of shell scripts in the POSTGRES distribution using 
.b monitor -c
are createdb, destroydb, createuser, and destroyuser.
.sp
\fI-d path\fR specifies the path name of the file or tty which you want
the frontend debugging messages to be written to; the default is not
to generate any debugging messages. 
.sp
\fI-q\fR specifies that the monitor should do its work quietly.
By default,
it prints welcome and exit messages
and the queries it sends to the backend.
If the \fI-q\fP flag is used,
none of this happens.
.sp
\fI-o options\fR specifies additonal options for the postgres backend.
This is only intended for use by postgres developers.
.lp
You may set environment variables to avoid typing the above options.
See the \fBENVIRONMENT VARIABLES\fR section below.
.uh "MESSAGES AND PROMPTS"
.lp
The terminal monitor gives a variety of messages to keep the user informed
of the status of the monitor and the query buffer.
.sp
When the terminal monitor is executed,
it gives the current date and time,
usually followed by the information in the
.b dayfile
(files).
.sp
The terminal monitor displays two kinds of messages:
.nf

go		The query buffer is empty and the terminal monitor is ready
		for input.  Anything typed will be added to the buffer.

*		This prompt is typed at the beginning of each line when the
		terminal monitor is waiting for input.
.sp
.uh "TERMINAL MONITOR COMMANDS"
.nf
.sp
 \\e		Enter the editor to edit the query buffer

 \\g		Submit query buffer to POSTGRES for execution

 \\h		Get on-line help

 \\i \fIfilename\fR	Include the file filename into the query buffer

 \\p		Print contents of the query buffer 

 \\q		Exit from the terminal monitor

 \\r		Reset (clear) the query buffer

 \\s		Escape to a \*(UU subshell.  To return to the
		terminal monitor, type \*(lqexit\*(rq at the shell prompt.

 \\t		Print current time

 \\w \fIfilename\fR	Store the query buffer to an external file

 \\\\		Produce a single backslash at the current location in query buffer
.sp
.uh "ENVIRONMENT VARIABLES"
.lp
You may set environment variables to avoid specifying command line
options.  These are as follows:
.sp
.(l
hostname:	PGHOST
port:		PGPORT
tty:		PGTTY
options:		PGOPTION
.)l
.sp
.uh "RETURN VALUE"
.lp
When executed with the
.b -c query
option
.i monitor
returns 0 to the shell on successful query completion, 1 otherwise.
.sp
.uh "SEE ALSO"
.lp
backend(unix), postmaster(unix), createdb(unix), destroydb(unix),
createuser(unix), destroyuser(unix)
