Move documentation to sgml sources.
This commit is contained in:
Thomas G. Lockhart
parent
ef58a2c285
commit
f5da9422be
|
|
@ -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.
|
||||
Loading…
Reference in New Issue