mirror of
https://github.com/postgres/postgres.git
synced 2025-08-19 23:22:23 +03:00
Move documentation to sgml sources.
This commit is contained in:
Thomas G. Lockhart
@@ -1,17 +0,0 @@
|
|||||||
#-------------------------------------------------------------------------
|
|
||||||
#
|
|
||||||
# Makefile
|
|
||||||
# Makefile for doc directory to install man pages
|
|
||||||
#
|
|
||||||
# IDENTIFICATION
|
|
||||||
# $Header: /cvsroot/pgsql/src/interfaces/libpq++/man/Attic/Makefile,v 1.5 1998/04/06 16:52:47 momjian Exp $
|
|
||||||
#
|
|
||||||
#-------------------------------------------------------------------------
|
|
||||||
|
|
||||||
SRCDIR= ../../..
|
|
||||||
include ../../../Makefile.global
|
|
||||||
|
|
||||||
install:
|
|
||||||
-mkdir $(POSTMANDIR)
|
|
||||||
-mkdir $(POSTMANDIR)/man3
|
|
||||||
cp *.3* $(POSTMANDIR)/man3
|
|
||||||
@@ -1,434 +0,0 @@
|
|||||||
.\"
|
|
||||||
.\" POSTGRES95 Data Base Management System
|
|
||||||
.\"
|
|
||||||
.\" Copyright (c) 1994-5 Regents of the University of California
|
|
||||||
.\"
|
|
||||||
.\" POSTGRES Data Base Management System
|
|
||||||
.\" Copyright (c) 1988,1994 Regents of the University of California
|
|
||||||
.\"
|
|
||||||
.\" Permission to use, copy, modify, and distribute this software and its
|
|
||||||
.\" documentation for any purpose, without fee, and without a written agreement
|
|
||||||
.\" is hereby granted, provided that the above copyright notice and this
|
|
||||||
.\" paragraph and the following two paragraphs appear in all copies.
|
|
||||||
.\"
|
|
||||||
.\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
|
|
||||||
.\" DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
|
|
||||||
.\" LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
|
|
||||||
.\" DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE
|
|
||||||
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
||||||
.\"
|
|
||||||
.\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
|
|
||||||
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
||||||
.\" AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
|
|
||||||
.\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO
|
|
||||||
.\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
|
|
||||||
.\"
|
|
||||||
.\"
|
|
||||||
.\" $Id: libpq++.3,v 1.1.1.1 1996/07/09 06:22:19 scrappy Exp $
|
|
||||||
.\"
|
|
||||||
.\" ------------------------------------------------------------------
|
|
||||||
.\" .(l, .)l
|
|
||||||
.\" fake "-me"-style lists
|
|
||||||
.de (l
|
|
||||||
.nf
|
|
||||||
.ie '\\$1'M' .in +0n
|
|
||||||
.el .in +5n
|
|
||||||
..
|
|
||||||
.de )l
|
|
||||||
.fi
|
|
||||||
.in
|
|
||||||
..
|
|
||||||
.\" .(C, .)C
|
|
||||||
.\" constant-width font blocks
|
|
||||||
.de (C
|
|
||||||
.ft C
|
|
||||||
.(b
|
|
||||||
.(l \\$1
|
|
||||||
.sp
|
|
||||||
..
|
|
||||||
.de )C
|
|
||||||
.sp
|
|
||||||
.)l
|
|
||||||
.)b
|
|
||||||
.ft R
|
|
||||||
..
|
|
||||||
.\" ------------------------------------------------------------------
|
|
||||||
.de SE
|
|
||||||
.nr si 0
|
|
||||||
.nr so 0
|
|
||||||
.nr $0 0
|
|
||||||
.nr $i \\n(si*\\n($0
|
|
||||||
.in \\n($i+\\n(po
|
|
||||||
..
|
|
||||||
.\" ------------------------------------------------------------------
|
|
||||||
.de SP
|
|
||||||
.he '\fB\\$1 (\\$2)'\\$3'\\$1 (\\$2)\fR'
|
|
||||||
..
|
|
||||||
.\" ------------------------------------------------------------------
|
|
||||||
.de SS
|
|
||||||
.PP
|
|
||||||
.B \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8
|
|
||||||
.PP
|
|
||||||
..
|
|
||||||
.\" ------------------------------------------------------------------
|
|
||||||
.SB
|
|
||||||
.ds II \s-1INGRES\s0
|
|
||||||
.ds PG \s-1POSTGRES95\s0
|
|
||||||
.ds UU \s-1UNIX\s0
|
|
||||||
.ds PQ \s-1POSTQUEL\s0
|
|
||||||
.ds LI \s-1LIBPQ++\s0
|
|
||||||
.ds PV 4.2
|
|
||||||
.SB
|
|
||||||
.TH INTRODUCTION LIBPQ++ 07/24/95
|
|
||||||
.XA 0 "Libpq++"
|
|
||||||
.BH "LIBPQ++"
|
|
||||||
.SH DESCRIPTION
|
|
||||||
\*(LI is the C++ API to \*(PG. \*(LI is a set of classes which allow
|
|
||||||
client programs to connect to the \*(PG backend server. These connections
|
|
||||||
come in two forms: a Database Class and a Large Object class.
|
|
||||||
.PP
|
|
||||||
The Database Class is intended for manipulating a database. You can
|
|
||||||
send all sorts of SQL queries to the \*(PG backend server and retrieve
|
|
||||||
the responses of the server.
|
|
||||||
.PP
|
|
||||||
The Large Object Class is intended for manipulating a large object
|
|
||||||
in a database. Although a Large Object instance can send normal
|
|
||||||
queries to the \*(PG backend server it is only intended for simple
|
|
||||||
queries that do not return any data. A large object should be seen
|
|
||||||
as a file stream. In future it should behave much like the C++ file
|
|
||||||
streams
|
|
||||||
.IR cin ,
|
|
||||||
.IR cout
|
|
||||||
and
|
|
||||||
.IR cerr .
|
|
||||||
This version of the documentation is based on the C library. Three
|
|
||||||
short programs are listed at the end of this section as examples of
|
|
||||||
\*(LI programming (though not necessarily of good programming).
|
|
||||||
.PP
|
|
||||||
There are several examples of \*(LI applications in the following
|
|
||||||
directory:
|
|
||||||
.(C
|
|
||||||
\&.../src/libpq++/examples
|
|
||||||
.)C
|
|
||||||
.XA 1 "Control and Initialization"
|
|
||||||
.SH "CONTROL AND INITIALIZATION"
|
|
||||||
.XA 2 "Environment Variables"
|
|
||||||
.SS "Environment Variables"
|
|
||||||
The following environment variables can be used to set up default
|
|
||||||
values for an environment and to avoid hard-coding database names into
|
|
||||||
an application program:
|
|
||||||
.TP 15n
|
|
||||||
.BR PGDATABASE
|
|
||||||
sets the default \*(PG database name.
|
|
||||||
.TP 15n
|
|
||||||
.BR PGHOST
|
|
||||||
sets the default server name.
|
|
||||||
.TP 15n
|
|
||||||
.BR PGOPTIONS
|
|
||||||
sets additional runtime options for the \*(PG backend.
|
|
||||||
.TP 15n
|
|
||||||
.BR PGPORT
|
|
||||||
sets the default communication port with the \*(PG backend.
|
|
||||||
.TP 15n
|
|
||||||
.BR PGTTY
|
|
||||||
sets the file or tty on which debugging messages from the backend server
|
|
||||||
are displayed.
|
|
||||||
.TP 15n
|
|
||||||
.BR PGREALM
|
|
||||||
sets the
|
|
||||||
.IR Kerberos
|
|
||||||
realm to use with \*(PG, if it is different from the local realm. If
|
|
||||||
.SM PGREALM
|
|
||||||
is set, \*(PG applications will attempt authentication with servers
|
|
||||||
for this realm and use separate ticket files to avoid conflicts with
|
|
||||||
local ticket files. This environment variable is only used if
|
|
||||||
.IR Kerberos
|
|
||||||
authentication is enabled.
|
|
||||||
.TP 15n
|
|
||||||
.BR PGAUTH
|
|
||||||
sets the type of authentication which should be used. Currently
|
|
||||||
only
|
|
||||||
.IR unauth ,
|
|
||||||
.IR krb4 ,
|
|
||||||
and
|
|
||||||
.IR krb5 .
|
|
||||||
are supported. Depending on whether you compiled in support for those.
|
|
||||||
.XA 1 "Database Connection Functions"
|
|
||||||
.SH "DATABASE ENVIRONMENT CLASS: PGenv"
|
|
||||||
The database environment class provides C++ objects for manipulating the
|
|
||||||
above environment variables.
|
|
||||||
.TP 15n
|
|
||||||
.BR PGenv
|
|
||||||
Create an environment for the running program.
|
|
||||||
.(C
|
|
||||||
PGenv()
|
|
||||||
PGenv(char* auth, char* host, char* port, char* option, char* tty)
|
|
||||||
.)C
|
|
||||||
The first form of this object's constructor sets up the defaults for
|
|
||||||
the program from the environment variables listed above.
|
|
||||||
The second allows the programmer to hardcode the values into the program.
|
|
||||||
The values of the second form relate directly to the environment variables
|
|
||||||
above.
|
|
||||||
.SH "DATABASE CLASS: PGdatabase"
|
|
||||||
The database class is a provides C++ objects that have a connection
|
|
||||||
to a backend server. To create such an object one first need
|
|
||||||
the apropriate environment for the backend to access.
|
|
||||||
The following constructors deal with making a connection to a backend
|
|
||||||
server from a C++ program.
|
|
||||||
.TP 15n
|
|
||||||
.BR PGdatabase
|
|
||||||
Make a new connection to a backend database server.
|
|
||||||
.(C
|
|
||||||
PGdatabase(PGenv *env, char *dbName);
|
|
||||||
.)C
|
|
||||||
After a PGdatabase has been created it should be checked to make sure
|
|
||||||
the connection to the database succeded before sending
|
|
||||||
queries to the object. This can easily be done by
|
|
||||||
retrieving the current status of the PGdatabase object with the
|
|
||||||
.IR status
|
|
||||||
command.
|
|
||||||
.BR PGdatabase::status
|
|
||||||
Returns the status of the PGdatabase object.
|
|
||||||
|
|
||||||
.(C
|
|
||||||
ConnStatus PGdatabase::status()
|
|
||||||
.)C
|
|
||||||
|
|
||||||
the following values are allowed
|
|
||||||
|
|
||||||
.(C
|
|
||||||
CONNECTION_OK
|
|
||||||
CONNECTION_BAD
|
|
||||||
.)C
|
|
||||||
|
|
||||||
.XA 1 "Query Execution Functions"
|
|
||||||
.SH "QUERY EXECUTION FUNCTIONS"
|
|
||||||
.TP 15n
|
|
||||||
.BR PGdatabase::exec
|
|
||||||
Submits a query to \*(PG and returns result status. In case of an error
|
|
||||||
.IR PGdatabase::errormessage
|
|
||||||
can be used to get more information on the error.
|
|
||||||
.(C
|
|
||||||
void
|
|
||||||
ExecStatusType PGdatabase::exec(char *query);
|
|
||||||
.)C
|
|
||||||
The following status results can be expected.
|
|
||||||
.(C
|
|
||||||
PGRES_EMPTY_QUERY,
|
|
||||||
PGRES_COMMAND_OK, /* the query was a command */
|
|
||||||
PGRES_TUPLES_OK, /* the query successfully returned tuples */
|
|
||||||
PGRES_COPY_OUT,
|
|
||||||
PGRES_COPY_IN,
|
|
||||||
PGRES_BAD_RESPONSE, /* an unexpected response was received */
|
|
||||||
PGRES_NONFATAL_ERROR,
|
|
||||||
PGRES_FATAL_ERROR
|
|
||||||
.)C
|
|
||||||
.IP
|
|
||||||
If the result status is PGRES_TUPLES_OK, then the following routines can
|
|
||||||
be used to retrieve the tuples returned by the query.
|
|
||||||
.IP
|
|
||||||
.BR PGdatabase::ntuples
|
|
||||||
returns the number of tuples (instances) in the query result.
|
|
||||||
.(C
|
|
||||||
int PGdatabase::ntuples();
|
|
||||||
.)C
|
|
||||||
.BR PGdatabase::nfields
|
|
||||||
returns the number of fields (attributes) in the query result.
|
|
||||||
.(C
|
|
||||||
int PGdatabase::nfields();
|
|
||||||
.)C
|
|
||||||
.BR PGdatabase::fieldname
|
|
||||||
returns the field (attribute) name associated with the given field index.
|
|
||||||
Field indices start at 0.
|
|
||||||
.(C
|
|
||||||
char* PGdatabase::fieldname(int field_index);
|
|
||||||
.)C
|
|
||||||
.BR PGdatabase::fieldnum
|
|
||||||
returns the field (attribute) index associated with the given field name.
|
|
||||||
.(C
|
|
||||||
int PGdatabase::fieldnum(char* field_name);
|
|
||||||
.)C
|
|
||||||
.BR PGdatabase::fieldtype
|
|
||||||
returns the field type of associated with the given field index or name.
|
|
||||||
The integer returned is an internal coding of the type. Field indices start
|
|
||||||
at 0.
|
|
||||||
.(C
|
|
||||||
Oid PGdatabase::fieldtype(int field_index);
|
|
||||||
Oid PGdatabase::fieldtype(char* field_name);
|
|
||||||
.)C
|
|
||||||
.BR PGdatabase::fieldsize
|
|
||||||
returns the size in bytes of the field associated with the given field
|
|
||||||
index or name. If the size returned is -1, the field is a variable length
|
|
||||||
field. Field indices start at 0.
|
|
||||||
.(C
|
|
||||||
int2 PGdatabase::fieldsize(int field_index);
|
|
||||||
int2 PGdatabase::fieldsize(char* field_name);
|
|
||||||
.)C
|
|
||||||
.BR PGdatabase::getvalue
|
|
||||||
returns the field (attribute) value. For most queries, the values
|
|
||||||
returned by
|
|
||||||
.IR PGdatabase::getvalue
|
|
||||||
is a null-terminated ASCII string representation
|
|
||||||
of the attribute value. If the query was a result of a
|
|
||||||
.BR BINARY
|
|
||||||
cursor, then the values returned by
|
|
||||||
.IR PGdatabase::getvalue
|
|
||||||
is the binary representation of the type in the internal format of the
|
|
||||||
backend server. It is the programmer's responsibility to cast and
|
|
||||||
convert the data to the correct C++ type. The value return by
|
|
||||||
.IR PGdatabase::getvalue
|
|
||||||
points to storage that is part of the PGdatabase structure. One must
|
|
||||||
explicitly copy the value into other storage if it is to be used past
|
|
||||||
the next query.
|
|
||||||
.(C
|
|
||||||
char* PGdatabase::getvalue(int tup_num, int field_index);
|
|
||||||
char* PGdatabase::getvalue(int tup_num, char* field_name);
|
|
||||||
.)C
|
|
||||||
.BR PGdatabase::getlength
|
|
||||||
returns the length of a field (attribute) in bytes. If the field
|
|
||||||
is a
|
|
||||||
.IR "struct varlena" ,
|
|
||||||
the length returned here does
|
|
||||||
.BR not
|
|
||||||
include the size field of the varlena, i.e., it is 4 bytes less.
|
|
||||||
.(C
|
|
||||||
int PGdatabase::getlength(int tup_num, int field_index);
|
|
||||||
int PGdatabase::getlength(int tup_num, char* field_name);
|
|
||||||
.)C
|
|
||||||
.BR PGdatabase::printtuples
|
|
||||||
prints out all the tuples and, optionally, the attribute names to the
|
|
||||||
specified output stream.
|
|
||||||
.(C
|
|
||||||
void PGdatabase::printtuples(
|
|
||||||
FILE* fout, /* output stream */
|
|
||||||
int printAttName,/* print attribute names or not*/
|
|
||||||
int terseOutput, /* delimiter bars or not?*/
|
|
||||||
int width /* width of column, variable width if 0*/
|
|
||||||
);
|
|
||||||
.)C
|
|
||||||
.XA 1 "Asynchronous Notification"
|
|
||||||
.SH "ASYNCHRONOUS NOTIFICATION"
|
|
||||||
\*(PG supports asynchronous notification via the
|
|
||||||
.IR LISTEN
|
|
||||||
and
|
|
||||||
.IR NOTIFY
|
|
||||||
commands. A backend registers its interest in a particular relation
|
|
||||||
with the LISTEN command. All backends that are listening on a
|
|
||||||
particular relation will be notified asynchronously when a NOTIFY of
|
|
||||||
that relation name is executed by another backend. No additional
|
|
||||||
information is passed from the notifier to the listener. Thus,
|
|
||||||
typically, any actual data that needs to be communicated is transferred
|
|
||||||
through the relation.
|
|
||||||
.PP
|
|
||||||
\*(LI applications are notified whenever a connected backend has
|
|
||||||
received an asynchronous notification. However, the communication from
|
|
||||||
the backend to the frontend is not asynchronous. The \*(LI application
|
|
||||||
must poll the backend to see if there is any pending notification
|
|
||||||
information. After the execution of a query, a frontend may call
|
|
||||||
.IR PGdatabase::notifies
|
|
||||||
to see if any notification data is currently available from the backend.
|
|
||||||
.TP 15n
|
|
||||||
.BR PGdatabase::notifies
|
|
||||||
returns the notification from a list of unhandled notifications from the
|
|
||||||
backend. Returns NULL if there is no pending notifications from the
|
|
||||||
backend.
|
|
||||||
.IR PGdatabase::notifies
|
|
||||||
behaves like the popping of a stack. Once a notification is returned
|
|
||||||
from
|
|
||||||
.IR PGdatabase::notifies,
|
|
||||||
it is considered handled and will be removed from the list of
|
|
||||||
notifications.
|
|
||||||
.(C
|
|
||||||
PGnotify* PGdatabase::notifies()
|
|
||||||
.)C
|
|
||||||
.PP
|
|
||||||
The second sample program gives an example of the use of asynchronous
|
|
||||||
notification.
|
|
||||||
.XA 1 "Functions Associated with the COPY Command"
|
|
||||||
.SH "FUNCTIONS ASSOCIATED WITH THE COPY COMMAND"
|
|
||||||
The
|
|
||||||
.IR copy
|
|
||||||
command in \*(PG has options to read from or write to the network
|
|
||||||
connection used by \*(LI. Therefore, functions are necessary to
|
|
||||||
access this network connection directly so applications may take full
|
|
||||||
advantage of this capability.
|
|
||||||
.TP 15n
|
|
||||||
.BR PGdatabase::getline
|
|
||||||
Reads a newline-terminated line of characters (transmitted by the
|
|
||||||
backend server) into a buffer
|
|
||||||
.IR string
|
|
||||||
of size
|
|
||||||
.IR length .
|
|
||||||
Like
|
|
||||||
.IR fgets (3),
|
|
||||||
this routine copies up to
|
|
||||||
.IR length "-1"
|
|
||||||
characters into
|
|
||||||
.IR string .
|
|
||||||
It is like
|
|
||||||
.IR gets (3),
|
|
||||||
however, in that it converts the terminating newline into a null
|
|
||||||
character.
|
|
||||||
.IP
|
|
||||||
.IR PGdatabase::getline
|
|
||||||
returns EOF at EOF, 0 if the entire line has been read, and 1 if the
|
|
||||||
buffer is full but the terminating newline has not yet been read.
|
|
||||||
.IP
|
|
||||||
Notice that the application must check to see if a new line consists
|
|
||||||
of the single character \*(lq.\*(rq, which indicates that the backend
|
|
||||||
server has finished sending the results of the
|
|
||||||
.IR copy
|
|
||||||
command. Therefore, if the application ever expects to receive lines
|
|
||||||
that are more than
|
|
||||||
.IR length "-1"
|
|
||||||
characters long, the application must be sure to check the return
|
|
||||||
value of
|
|
||||||
.IR PGdatabase::getline
|
|
||||||
very carefully.
|
|
||||||
.IP
|
|
||||||
.(C
|
|
||||||
int PGdatabase::getline(char* string, int length)
|
|
||||||
.)C
|
|
||||||
.TP 15n
|
|
||||||
.BR PGdatabase::putline
|
|
||||||
Sends a null-terminated
|
|
||||||
.IR string
|
|
||||||
to the backend server.
|
|
||||||
.IP
|
|
||||||
The application must explicitly send the single character \*(lq.\*(rq
|
|
||||||
to indicate to the backend that it has finished sending its data.
|
|
||||||
.(C
|
|
||||||
void PGdatabase::putline(char* string)
|
|
||||||
.)C
|
|
||||||
.TP 15n
|
|
||||||
.BR PGdatabase::endcopy
|
|
||||||
Syncs with the backend. This function waits until the backend has
|
|
||||||
finished processing the copy. It should either be issued when the
|
|
||||||
last string has been sent to the backend using
|
|
||||||
.IR PGdatabase::putline
|
|
||||||
or when the last string has been received from the backend using
|
|
||||||
.IR PGdatabase::getline .
|
|
||||||
It must be issued or the backend may get \*(lqout of sync\*(rq with
|
|
||||||
the frontend. Upon return from this function, the backend is ready to
|
|
||||||
receive the next query.
|
|
||||||
.IP
|
|
||||||
The return value is 0 on successful completion, nonzero otherwise.
|
|
||||||
.(C
|
|
||||||
int PGdatabase::endcopy()
|
|
||||||
.)C
|
|
||||||
As an example:
|
|
||||||
.(C
|
|
||||||
PGdatabase data;
|
|
||||||
data.exec("create table foo (a int4, b char16, d float8)");
|
|
||||||
data.exec("copy foo from stdin");
|
|
||||||
data.putline("3\etHello World\et4.5\en");
|
|
||||||
data.putline("4\etGoodbye World\et7.11\en");
|
|
||||||
\&...
|
|
||||||
data.putline(".\en");
|
|
||||||
data.endcopy();
|
|
||||||
.)C
|
|
||||||
.SH BUGS
|
|
||||||
The query buffer is 8192 bytes long, and queries over that length will
|
|
||||||
be silently truncated.
|
|
||||||
.bp
|
|
||||||
The PGlobj class is largely untested. Use with caution.
|
|
||||||
Reference in New Issue
Block a user