From f5da9422bead14d1250a8c5618c5c037189fee5e Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Sat, 10 Oct 1998 17:07:16 +0000 Subject: [PATCH] Move documentation to sgml sources. --- src/interfaces/libpq++/man/Makefile | 17 -- src/interfaces/libpq++/man/libpq++.3 | 434 --------------------------- 2 files changed, 451 deletions(-) delete mode 100644 src/interfaces/libpq++/man/Makefile delete mode 100644 src/interfaces/libpq++/man/libpq++.3 diff --git a/src/interfaces/libpq++/man/Makefile b/src/interfaces/libpq++/man/Makefile deleted file mode 100644 index ab8752021a..0000000000 --- a/src/interfaces/libpq++/man/Makefile +++ /dev/null @@ -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 diff --git a/src/interfaces/libpq++/man/libpq++.3 b/src/interfaces/libpq++/man/libpq++.3 deleted file mode 100644 index ebca7ab7bb..0000000000 --- a/src/interfaces/libpq++/man/libpq++.3 +++ /dev/null @@ -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. -- 2.40.0