head	1.17;
access;
symbols;
locks; strict;
comment	@# @;


1.17
date	92.07.31.17.02.31;	author mer;	state Exp;
branches;
next	1.16;

1.16
date	92.07.22.19.26.44;	author clarsen;	state Exp;
branches;
next	1.15;

1.15
date	92.07.20.18.55.37;	author mer;	state Exp;
branches;
next	1.14;

1.14
date	92.07.15.01.57.02;	author clarsen;	state Exp;
branches;
next	1.13;

1.13
date	92.07.13.03.45.59;	author ptong;	state Exp;
branches;
next	1.12;

1.12
date	92.07.12.21.10.19;	author ptong;	state Exp;
branches;
next	1.11;

1.11
date	92.06.25.23.58.38;	author mao;	state Exp;
branches;
next	1.10;

1.10
date	92.06.17.22.24.05;	author mer;	state Exp;
branches;
next	1.9;

1.9
date	92.03.25.19.25.31;	author clarsen;	state Exp;
branches;
next	1.8;

1.8
date	92.01.30.19.39.44;	author mer;	state Exp;
branches;
next	1.7;

1.7
date	91.11.13.05.20.12;	author mer;	state Exp;
branches;
next	1.6;

1.6
date	91.11.12.06.09.09;	author mer;	state Exp;
branches;
next	1.5;

1.5
date	91.08.16.00.32.57;	author mer;	state Exp;
branches;
next	1.4;

1.4
date	91.03.09.05.27.59;	author kemnitz;	state Exp;
branches;
next	1.3;

1.3
date	91.02.25.19.17.21;	author mike;	state Exp;
branches;
next	1.2;

1.2
date	90.07.20.08.54.39;	author claire;	state Exp;
branches;
next	1.1;

1.1
date	90.07.18.16.25.41;	author mao;	state Exp;
branches;
next	;


desc
@use of libpq.a for user-level database apps that use postgres
@


1.17
log
@clean up description of PQexec
@
text
@.\" XXX standard disclaimer belongs here....
.\" $Header: /home/postgres/mer/ref/RCS/libpq,v 1.16 1992/07/22 19:26:44 clarsen Exp mer $
.SS LIBPQ 6/14/90
.XA 0 "Section 5 \*- Libpq"
.sp 2i
.ps 14
.ce
.b "SECTION 5 \*- LIBPQ"
.sp 3
.uh NAME
.lp
libpq \*- programmer's interface to \*(PP
.uh DESCRIPTION
.lp
LIBPQ is the programmer's interface to \*(PP.  LIBPQ is a set of
library routines which allow queries to pass to the \*(PP back-end
and instances to return through an IPC channel.
.lp
This version of the documentation is based on the C library.
.uh "CONTROL AND INITIALIZATION"
.lp
.uh VARIABLES
.lp
The following five environment variables can be used to set
up default values for an environment and to avoid hard-coding
database names into an application program:
.lp
.(l
.bu
\fBPGHOST\fR sets the default server name.
.bu
\fBPGDATABASE\fR sets the default \*(PP database name.
.bu
\fBPGPORT\fR sets the default communication port with the \*(PP back-end.
.bu
\fBPGTTY\fR sets the tty on the PQhost back-end on which debugging messages are displayed.
.)l
.lp
The following internal variables of libpq can be accessed by
the programmer:
.lp
.(1
.nf
.ft C
char *PQhost;           /* the server on which \*(PP
                           back-end is running. */

char *PQport = NULL;    /* The communication port with the
                           \*(PP back-end. */

char *PQtty;            /* The tty on the PQhost back-end on
                           which back-end messages are
                           displayed. */

char *PQoption;         /* Optional arguements to the back-end */

char *PQdatabase;       /* Back-end database to access */

int  PQportset = 0;     /* 1 if communication with
                           back-end is established */

int  PQxactid = 0;      /* Transaction ID of the current
                           transaction */

int  PQtracep = 0;      /* 1 to print out front-end
                           debugging messages */

int  PQAsyncNotifyWaiting = 0; /* 1 if one or more asynchronous
                                  notifications have been
                                  triggered */
.ft
.)1
.fi
.uh "QUERY EXECUTION FUNCTIONS"
.lp
The following routines control the execution of queries
from a C program.

.(1
PQsetdb \*- Make the specified database the current database, 

.nf
.ft C
void PQsetdb ( dbname )
	char	*dbname;
.ft

PQsetdb also resets communication via PQreset (see below).

PQdb \*- Return the current database being accessed.

.ft C
char * PQdb ()
.ft
.)1
.fi
.lp
Returns the name of the \*(PP database
being accessed, or NIL if no database is open.
Only one database can be accessed at a time.  The database
name is a string limited to 16 characters.
.lp
.nf
.(1
PQreset \*- Reset the communication port with the back-end in case of errors.

.ft C
void PQreset()
.ft

.fi
This function will close the IPC socket connection to the backend thereby
causing the next PQexec() call to ask for a new one from the postmaster.
When the backend notices the socket was closed it will exit, and when the
postmaster is asked for the new connection it will start a new back-end.
.nf

PQfinish \*- Close communication ports with the back-end.

.ft C
void PQfinish ()
.ft
.)1
.fi
.lp
Terminates communications and frees up the memory taken up
by the libpq buffer.
.nf

.(1
PQfn \*- Send a function call to the \*(PP backend.

.ft C
char *PQfn(fnid, result_buf, result_len,
           result_is_int, args, nargs)
	int fnid;
	int *result_buf;    /* can't use void, the */
	int result_len;     /* compiler complains  */
	int result_is_int;
	PQArgBlock *args;
	int nargs;
.ft

.fi
PQfn provides access to the \*(PP fastpath facility, a trapdoor into
the system internals.  See \fBFASTPATH\fR.
.nf

.(1
PQexec \*- Submit a query to \*(PP.  

.ft C
char *	PQexec (query)
	char	* query;
.ft
.)1
.fi
.lp
This function returns a status indicator or an error message.  If the query
returns data (e.g. fetch), PQexec returns a string consisting of 'P' followed
by the name of the portal buffer.  
When the query does not return instances, PQexec
will return a string consisting of 'C' followed by the command tag (e.g.
"CREPLACE").  If an error occured during the execution of the query 
PQexec will return (for historical reasons) an "R".

.uh "PORTAL FUNCTIONS"
.lp
A portal is a \*(PP buffer from which instances can be fetched.
Each portal has a string name (currently limited to 16 bytes).
A portal is initialized by submitting a retrieve statement
using the PQexec function, for example:
.(l
.ft C
retrieve portal foo ( EMP.all )
.ft
.)l
.lp
The programmer can then move data from the portal into LIBPQ
by executing a \fIfetch\fR statement, e.g:
.(l
.ft C
fetch 10 in \fIfoo\fR
.ft

.ft C
fetch all in \fIfoo\fR
.ft
.)l
.lp
If no portal name is specified in a query, the default
portal name is the string "blank", known as the "blank portal."
All qualifying instances in a blank portal are fetched
immediately, without the need for the programmer to issue a
seperate fetch command.
.lp
Data fetched from a portal into LIBPQ is moved into a portal
buffer.  Portal names are mapped to portal buffers through
an internal table.  Each instance in a portal buffer has
an index number locating its position in the buffer.  In addition,
each field in an instance has a name and a field number.
.lp
A single retrieve command can return multiple types
of instances.
This can happen if a \*(PP function is executed
in the evaluation of a query or if the query
returns multiple instance types from an inheritance
hierarchy.
Consequently, the instances in a portal are set up
in groups.
Instances in the same group are guaranteed to have the
same instance format.
.lp
Portals that are associated with normal user commands
are called synchronous.
In this case, the application program is expected
to issue a retrieval followed by one or more
fetch commands.
The functions that follow can now be used to
manipulate data in the portal.
.(l
PQnportals \*- Return the number of open portals.

.ft C
int PQnportals ( rule_p )
	int	rule_p ;
.ft

If rule_p is not 0, then only return the number of asynchronous portals.

PQpnames \*- Return all portal names.

.ft C
void PQpnames  ( pnames, rule_p)
	char	*pnames [MAXPORTALS];
	int	rule_p ;
.ft

If rule_p is not 0, then only return the names of asynchronous
portals.

PQparray \*- Return the portal buffer given a portal name.

.ft C
PortalBuffer * PQparray ( pname )
	char	*pname;
.ft

PQclear \*- free storage claimed by named portal.

.ft C
void PQclear ( pname )
	char	*pname;
.ft

PQntuples \*- Return the number of instances in a portal buffer.

.ft C
int PQntuples (portal)
	PortalBuffer	*portal;
.ft

PQngroups \*- Return the number of instance groups in a portal buffer.

.ft C
int PQngroups (portal)
	PortalBuffer *portal
.ft

PQntuplesGroup \*- Return the number of instances in an instance group.

.ft C
int PQntuplesGroup (portal, group_index)
	PortalBuffer	*portal;
	int	group_index;
.ft

PQnfieldsGroup \*- Return the number of fields in an instance group.

.ft C
int PQnfieldsGroup ( portal, group_index)
	PortalBuffer	*portal;
	int	group_index;
.ft

PQfnameGroup \*- Return the field name given the group and field index.

.ft C
char * PQfnameGroup (portal, group_index, field_number )
	PortalBuffer	*portal;
	int	group_index;
	int	field_number;
.ft

PQfnumberGroup \*- Return the field number (index) given the group index and field name.

.ft C
int PQfnumberGroup (portal, group_index, field_name)
	PortalBuffer	*portal;
	int	group_index;
	char	*field_name;
.ft

PQgetgroup \*- Returns the index of the group that a particular instance is in.

.ft C
int PQgetgroup ( portal, tuple_index )
	PortalBuffer	*portal;
	int	tuple_index;
.ft

PQnfields \*- Return the number of fields in an instance.

.ft C
int PQnfields (portal, tuple_index )
	PortalBuffer	*portal;
	int	tuple_index;
.ft

PQfnumber \*- Return the field index of a given field name within an instance.

.ft C
int PQfnumber ( portal, tuple_index, field_name)
	PortalBuffer	*portal;
	int	tuple_index;
	char	*field_name;
.ft

PQfname \*- Return the name of a field.

.ft C
char * PQfname ( portal, tuple_index, field_number )
	PortalBuffer	*portal;
	int	tuple_index;
	int	field_number;
.ft

PQftype \*- Return the type of a field.  

.ft C
int PQftype ( portal, tuple_index, field_number )
	PortalBuffer	*portal;
	int	tuple_index;
	int	field_number;
.ft

The type returned is an internal coding of a type.

PQsametype \*- Return 1 if two instances have the same attributes.

.ft C
int PQsametype ( portal, tuple_index1, tuple_index2 )
	PortalBuffer	*portal;
	int	tuple_index1, tuple_index2;
.ft

PQgetvalue \*- Return an attribute (field) value.  

.ft C
char * PQgetvalue ( portal, tuple_index, field_number )
	PortalBuffer	*portal;
	int	tuple_index;
	int	field_number;
.ft

.ft

PQgetlength \*- Return the length of an attribute (field) value in bytes.
If the field is a varlena, the length of the attribute returned here
does not include the longword size field of the varlena, e.g. it is 4
bytes less.

.ft C
char * PQgetlength ( portal, tuple_index, field_number )
	PortalBuffer	*portal;
	int	tuple_index;
	int	field_number;
.ft

PQNotifies \*- Return the list of relations on which notification has occurred.

.ft C
PQNotifyList *PQNotifies()
.ft

PQRemoveNotify \*- Remove the notification from the list of unhandled 
		   notifications.

.ft C
PQNotifyList *PQRemoveNotify(pqNotify)
	PQNotifyList *pqNotify;
.ft
.)l
.lp
If the portal is blank, or specified with the
.b portal 
keyword, all
values are returned as strings.  It is the programmer's responsibility
to convert them to the correct type.  If the portal is specified with the
.b iportal
keyword, all values are returned in internal format, namely in the format 
generated by the
.i input
function specified through the 
.b definetype
command.  Again, it is the programmer's responsibility to convert the
data to the correct type.

.uh "ASYNCHRONOUS PORTALS/NOTIFICATION"
.lp
Asynchronous portals, query results of rules, are implemented using
two mechanisms: relations and notification.  The query result is
transferred through a relation.  The notification is done with special
postquel commands and frontend/backend protocol.

Referring to the second sample program, after executing "listen
relation_name" in the frontend process, periodically check
PQAsyncNotifyWaiting.  If it is non-zero, then the "notify
relation_name" command has been executed by some backend.  Immediately
clear PQAsyncNotifyWaiting, then do a NULL query, i.e.  PQexec(" "),
to retrieve the actual notification data.  Then call PQNotifies() to
get the list of relations on which notification has occurred.  After
handling the notification, do PQRemoveNotify on each element of the
list that has been handled to prevent further handling by you.

.uh "FUNCTIONS ASSOCIATED WITH THE COPY COMMAND"
.lp
The
.i copy
command in \*(PP has options to read from or write to the network
connection used by LIBPQ.  Therefore, functions are necessary to access
this network connection directly so applications may take full advantage
of this capability.
.lp
For more information about the 
.i copy
command, see copy(commands).
.lp

.(1
.ft C
PQgetline(string, length)
.ft
\*- Reads a null-terminated line into string.

.ft C
char *string;
int length
.ft

.ft C
PQputline(string)
.ft
\*- Sends a null-terminated string.

.ft C
char *string;
.ft

.ft C
int
PQendcopy()
.ft
\*- Syncs with the back-end.

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 PQputline() or when the last string has been received from
the backend using PGgetline().  It must be issued or the backend may get
"out of sync" with the frontend.  Upon return from this function, the
backend is ready to receive the next query.

The return value is 0 on successful completion, nonzero otherwise.

\fBFor Example:\fR

.nf
.ft C
PQexec("create foo (a=int4, b=char16, d=float8)");
PQexec("copy foo from stdin");
PQputline("3<TAB>hello world<TAB>4.5\n");
PQputline("4<TAB>goodbye world<TAB>7.11");
...
PQputline(".\en");
PQendcopy();
.ft
.fi
.)1

.uh "TRACING FUNCTIONS"
.lp
.(1
PQtrace \*- Enable tracing.

.ft C
void PQtrace ()
.ft

The routine sets the PQtracep variable to 1 which causes debug messages to
be printed.  You should note that the
messages will be printed to stdout by default.  If you would like different
behavior you must set the variable FILE *debug_port to the appropriate stream.

PQuntrace \*- Disable tracing.

.ft C
void PQuntrace ()
.ft
.)1
.uh BUGS
.lp
The query buffer is only 8192 bytes long, and queries over that
length will be silently truncated.

.uh "SAMPLE PROGRAM"
.lp
.(1
.nf
.ft C
/*
 * testlibpq.c \*-
 * 	Test the C version of Libpq, the \*(PP frontend library.
 */
#include <stdio.h>
#include "libpq.h"

main ()
{
    int i, j, k, g, n, m, t;
    PortalBuffer *p;
    char pnames[MAXPORTALS][portal_name_length];

    /* Specify the database to access. */
    PQsetdb ("pic_demo");

    /* Start a transaction block for eportal */
    PQexec ("begin");

    /* Fetch instances from the EMP class. */
    PQexec ("retrieve portal eportal (EMP.all)");
    PQexec ("fetch all in eportal");

    /* Examine all the instances fetched. */
    p = PQparray ("eportal");
    g = PQngroups (p);
    t = 0;
    
    for (k = 0; k < g; k++) {
	printf ("\enA new instance group:\en");
	n = PQntuplesGroup (p, k);
	m = PQnfieldsGroup (p, k);

	/* Print out the attribute names. */
	for (i = 0; i < m; i++)
	    printf ("%-15s", PQfnameGroup (p, k, i));
	printf ("\en");
    
	/* Print out the instances. */
	for (i = 0; i < n; i++) {
	    for (j = 0; j < m; j++)
		printf("%-15s", PQgetvalue(p, t+i, j));
	    printf ("\en");
	}
	t += n;
    }

    /* Close the portal. */
    PQexec ("close eportal");

    /* End the transaction block */
    PQexec("end");

    /* Try out some other functions. */
    
    /* Print out the number of portals. */
    printf ("\enNumber of portals open: %d.\en",
            PQnportals ());

    /* If any tuples are returned by rules, print out
     * the portal name. */
    if (PQnportals (1)) {
	printf ("Tuples are returned by rules. \en");
	PQpnames (pnames, 1);
	for (i = 0; i < MAXPORTALS; i++)
	    if (pnames[i] != NULL)
		printf ("portal used by rules: %s\en", pnames[i]);
    }

    /* finish execution. */
    PQfinish ();
}
.ft
.)1

.uh "SAMPLE PROGRAM 2"
.lp
.(1
.nf
.ft C
/*
 * Testing of asynchronous portal interface.
 * 
 * Do the following at the monitor:
 *

 create test1 (i = int4) \eg
 create test1a (i = int4) \eg

 define rule r1 is on append to test1 do
    [append test1a (i = new.i)
    notify test1a]

 \eg
 * Then start up this process.

 append test1 (i = 10) \eg

 * The value i=10 should be printed by this process.
 */

#include "tmp/simplelists.h"
#include "tmp/libpq.h"

void main()
{
    extern int PQAsyncNotifyWaiting;
    PQNotifyList *l;
    PortalBuffer *portalbuf;
    char *res;
    int ngroups,tupno, grpno, ntups, nflds;
    PQsetdb(getenv("USER"));

    PQexec("listen test1a");

    while(1) {
        sleep(1);
        if (PQAsyncNotifyWaiting) {
	    PQAsyncNotifyWaiting = 0;
            PQexec(" ");
            l = PQnotifies();
            if (l != NULL) {
                printf("notification on relation %s\en",
		       l->relname);
                res = PQexec("retrieve (test1a.i)");
                if (*res == 'E') {
                    fprintf(stderr,"%s\enfailed",++res);
                    goto exit_error;
                }
                if (*res != 'P') {
                    fprintf(stderr,"%s\enno portal",++res);
                }
                /* get tuples in relation */
                portalbuf = PQparray(++res);
                ngroups = PQngroups(portalbuf);
                for (grpno = 0; grpno < ngroups; grpno++) {
                    ntups = PQntuplesGroup(portalbuf,grpno);
		    nflds = PQnfieldsGroup(portalbuf,grpno);
                    if (nflds != 1) {
                        fprintf(stderr,
			  "expected 1 attributes, got %d\en",
			  nflds);
                        goto exit_error;
                    }
                    for (tupno = 0; tupno < ntups; tupno++) {
                        printf("got i=%s\en",
			  PQgetvalue(portalbuf,tupno,0));
                    }
                }
                break;
            }
        }
    }

    PQfinish();
    exit(0);
  exit_error:
    PQfinish();
    exit(1);

}
.ft
.)1

.uh "SAMPLE PROGRAM 3"
.lp
.(1
.nf
.ft C
/*
 * Testing of new binary portal interface.
 * 
 * Do the following at the monitor:
 *

 create test1 (i = int4,d = float4,p = polygon) \eg
 append test1 (i = 7, d=3.567,p="(1.0,2.0,3.0,4.0)"::polygon) \eg

 -- Anything else you can think of. 
 * Start up this program.
 * The correct contents of test1 should be printed
 */

#include "tmp/simplelists.h"
#include "tmp/libpq.h"
#include "utils/geo-decls.h"

void main()
{
    extern int PQAsyncNotifyWaiting;
    PQNotifyList *l;
    PortalBuffer *portalbuf;
    char *res;
    int ngroups,tupno, grpno, ntups, nflds;
    PQsetdb(getenv("USER"));

    PQexec("begin");
    res = (char *)PQexec("retrieve iportal junk (test1.all)");
    if (*res == 'E') {
	fprintf(stderr,"%s\enfailed",++res);
	goto exit_error;
    }
    res = (char *)PQexec("fetch all in junk");
    if (*res != 'P') {
	fprintf(stderr,"\enno portal");
	goto exit_error;
    }
    /* get tuples in relation */
    portalbuf = PQparray(++res);
    ngroups = PQngroups(portalbuf);
    for (grpno = 0; grpno < ngroups; grpno++) {
	ntups = PQntuplesGroup(portalbuf, grpno);
	if ((nflds = PQnfieldsGroup(portalbuf, grpno)) != 3) {
	    fprintf(stderr, "expected 3 attributes, got %d\en", nflds);
	    goto exit_error;
	}
	for (tupno = 0; tupno < ntups; tupno++) {
	    int *bla1;
	    char *bla2;
	    POLYGON *bla3;
	    bla1 = (int *)PQgetvalue(portalbuf,tupno,0);
	    bla2 = PQgetvalue(portalbuf,tupno,1);
	    bla3 = PQgetvalue(portalbuf,tupno,2)-4;

	    printf ("got i=%d(%d bytes), d=(%f)(%d bytes)|%x|%x|%x|%x\en\e
 Polygon(%d bytes)\e
  %d points (%f,%f,%f,%f)\en",
		    *bla1,PQgetlength(portalbuf,tupno,0),
		    *((float *)bla2),
		    PQgetlength(portalbuf,tupno,1),
		    *bla2,*(bla2+1),*(bla2+2),*(bla2+3),
		    PQgetlength(portalbuf,tupno,2),
		    bla3->npts,
		    bla3->boundbox.xh,bla3->boundbox.yh,
		    bla3->boundbox.xl,bla3->boundbox.yl);
	}
    }

    PQexec("end");
    PQfinish();
    exit(0);
  exit_error:
    PQexec("end");
    PQfinish();
    exit(1);

}
.ft
.)1
@


1.16
log
@fix syntax error
@
text
@d2 1
a2 1
.\" $Header: /usr/local/dev/postgres/mastertree/ref/RCS/libpq,v 1.15 1992/07/20 18:55:37 mer Exp clarsen $
d159 4
a162 4
This function returns a status indicator or an error message.  If the
query submitted was a retrieve then PQexec returns a string consisting
of a 'P' followed by the portal name.  If no portal was specified the
portal name will be "blank".  When the query was not a retrieve PQexec
d165 1
a165 5
PQexec will return "R".  You might be wondering "why an 'R'?"  The answer
is that this stems from libpq's history.  It used to be the case that
when libpq received an error message from the backend it would attempt
to \fIreset\fR communications.  Thus it returned (and still returns) an 'R' 
to the application program.
@


1.15
log
@fix poor use of backslash characters.
@
text
@d2 1
a2 1
.\" $Header: /home/postgres/mer/ref/RCS/libpq,v 1.14 1992/07/15 01:57:02 clarsen Exp mer $
d372 1
a372 1
PQgetlen \*- Return the length of an attribute (field) value in bytes.
d378 1
a378 1
char * PQgetlen ( portal, tuple_index, field_number )
@


1.14
log
@add function to get length of internal data.
@
text
@d2 1
a2 1
.\" $Header: /usr/local/dev/postgres/mastertree/ref/RCS/libpq,v 1.13 1992/07/13 03:45:59 ptong Exp clarsen $
d646 1
a646 1
                printf("notification on relation %s\n",
d650 1
a650 1
                    fprintf(stderr,"%s\nfailed",++res);
d654 1
a654 1
                    fprintf(stderr,"%s\nno portal",++res);
d664 1
a664 1
			  "expected 1 attributes, got %d\n",
d669 1
a669 1
                        printf("got i=%s\n",
d699 2
a700 2
 create test1 (i = int4,d = float4,p = polygon) \g
 append test1 (i = 7, d=3.567,p="(1.0,2.0,3.0,4.0)"::polygon) \g
d723 1
a723 1
	fprintf(stderr,"%s\nfailed",++res);
d728 1
a728 1
	fprintf(stderr,"\nno portal");
d737 1
a737 1
	    fprintf(stderr, "expected 3 attributes, got %d\n", nflds);
d748 3
a750 3
	    printf ("got i=%d(%d bytes), d=(%f)(%d bytes)|%x|%x|%x|%x\n\
 Polygon(%d bytes)\
  %d points (%f,%f,%f,%f)\n",
@


1.13
log
@Fixed up formating
@
text
@d2 1
a2 1
.\" $Header: /home/postgres/mer/refs/RCS/libpq,v 1.12 1992/07/12 21:10:19 ptong Exp ptong $
d370 14
d694 1
a694 1
 * Testing of binary portal interface.
d699 2
a700 2
 create test1 (i = int4,d = float4) \eg
 append test1 (i = 7, d=3.567) \eg
d706 1
d709 1
d721 1
a721 2
    res = (char *)
	  PQexec("retrieve iportal junk (test1.all)");
d723 2
a724 2
        fprintf(stderr,"%s\nfailed",++res);
        goto exit_error;
d728 2
a729 2
        fprintf(stderr,"\nno portal");
        goto exit_error;
d735 25
a759 19
        ntups = PQntuplesGroup(portalbuf, grpno);
	nflds = PQnfieldsGroup(portalbuf, grpno);
        if (nflds != 2) {
            fprintf(stderr,
		"expected 2 attributes, got %d\n",
		nflds);
            goto exit_error;
        }
        for (tupno = 0; tupno < ntups; tupno++) {
            int *bla1;
            char *bla2;
            bla1 = (int *)PQgetvalue(portalbuf,tupno,0);
            bla2 = PQgetvalue(portalbuf,tupno,1);

            printf ("got i=%d, d=(%f)|%x|%x|%x|%x\n",
		    *bla1,*((float *)bla2),
                    *bla2,*(bla2+1),*(bla2+2),
		    *(bla2+3));
        }
@


1.12
log
@Changed references to POSTGRES to the macro \*(PP.
@
text
@d2 1
a2 1
.\" $Header: /home/postgres/mer/refs/RCS/libpq,v 1.11 1992/06/25 23:58:38 mao Exp ptong $
d44 3
a46 2
char	*PQhost ;	/* the server on which \*(PP back-end
			   is running. */
d48 2
a49 2
char	*PQport = NULL ;	/* The communication port with the
				   \*(PP back-end. */
d51 3
a53 2
char	*PQtty;		/* The tty on the PQhost back-end on which
			   back-end messages are displayed. */
d55 1
a55 1
char	*PQoption ;	/* Optional arguements to the back-end */
d57 1
a57 1
char	*PQdatabase ;	/* Back-end database to access */
d59 2
a60 1
int	PQportset = 0;	/* 1 if communication with back-end is established */
d62 2
a63 1
int	PQxactid = 0 ;	/* Transaction ID of the current transaction */
d65 2
a66 1
int	PQtracep = 0 ;	/* 1 to print out front-end debugging messages */
d68 4
a71 2
int     PQAsyncNotifyWaiting = 0; /* 1 if one or more asynchronous 
				     notifications have been triggered */
d83 1
d86 1
d92 1
d94 1
d107 1
d109 1
d120 1
d122 1
d133 3
a135 1
char *PQfn(fnid, result_buf, result_len, result_is_int, args, nargs)
d137 2
a138 2
	int *result_buf;    /* can't use void, the compiler complains */
	int result_len;
d142 1
d152 1
d155 1
d178 3
a180 1
\fBretrieve portal\fR foo ( EMP.all )
d186 7
a192 3
\fBfetch 10 in \fIfoo\fR

\fBfetch all in \fIfoo\fR
d228 1
d231 1
d237 1
d241 1
d248 1
d251 1
d255 1
d258 1
d262 1
d265 1
d269 1
d272 1
d276 1
d280 1
d284 1
d288 1
d292 1
d297 1
d301 1
d306 1
d310 1
d314 1
d318 1
d322 1
d326 1
d331 1
d335 1
d340 1
d344 1
d349 1
d355 1
d359 1
d362 2
d368 1
d372 1
d374 1
d379 1
d382 2
a383 1
.)1
d399 2
a400 1
.uh "ASYNCHRONOUS PORTALS/NOTIFICATION" 
d427 1
a427 1
command, see copy(postquel).
d431 4
a434 1
PQgetline(string, length) \*- Reads a null-terminated line into string.
d436 1
d439 1
d441 4
a444 1
PQputline(string) \*- Sends a null-terminated string.
d446 1
d448 1
d450 1
d452 3
a454 1
PQendcopy() \*- Syncs with the back-end.
d468 1
d476 1
d485 1
d487 1
d496 1
d498 1
d509 1
d551 1
a551 1
		printf ("%-15s", PQgetvalue (p, t+i, j));
d566 2
a567 1
    printf ("\enNumber of portals open: %d.\en", PQnportals ());
d569 2
a570 1
    /* If any tuples are returned by rules, print out the portal name. */
d582 1
d589 1
d632 2
a633 1
                printf("notification on relation %s\n",l->relname);
d646 6
a651 3
                    ntups = PQntuplesGroup(portalbuf, grpno);
                    if ((nflds = PQnfieldsGroup(portalbuf, grpno)) != 1) {
                        fprintf(stderr, "expected 1 attributes, got %d\n", nflds);
d655 2
a656 1
                        printf ("got i=%s\n",PQgetvalue(portalbuf,tupno,0));
d671 1
d678 1
d705 2
a706 1
    res = (char *)PQexec("retrieve iportal junk (test1.all)");
d721 5
a725 2
        if ((nflds = PQnfieldsGroup(portalbuf, grpno)) != 2) {
            fprintf(stderr, "expected 2 attributes, got %d\n", nflds);
d734 4
a737 2
            printf ("got i=%d, d=(%f)|%x|%x|%x|%x\n", *bla1,*((float *)bla2),
                    *bla2,*(bla2+1),*(bla2+2),*(bla2+3));
d750 1
a750 1

@


1.11
log
@PGOPTION no longer passed to the back end
@
text
@d2 1
a2 1
.\" $Header: /private/mao/postgres/ref/RCS/libpq,v 1.10 1992/06/17 22:24:05 mer Exp mao $
d15 2
a16 2
LIBPQ is the programmer's interface to Postgres.  LIBPQ is a set of
library routines which allow queries to pass to the Postgres back-end
d32 1
a32 1
\fBPGDATABASE\fR sets the default Postgres database name.
d34 1
a34 1
\fBPGPORT\fR sets the default communication port with the POSTGRES back-end.
d44 1
a44 1
char	*PQhost ;	/* the server on which POSTGRES back-end
d48 1
a48 1
				   POSTGRES back-end. */
d87 1
a87 1
Returns the name of the POSTGRES database
d116 1
a116 1
PQfn \*- Send a function call to the POSTGRES backend.
d127 1
a127 1
PQfn provides access to the POSTGRES fastpath facility, a trapdoor into
d132 1
a132 1
PQexec \*- Submit a query to POSTGRES.  
d153 1
a153 1
A portal is a POSTGRES buffer from which instances can be fetched.
d354 1
a354 1
command in POSTGRES has options to read from or write to the network
d426 1
a426 1
 * 	Test the C version of Libpq, the POSTGRES frontend library.
@


1.10
log
@move to groff and fix some errors that occur from the move
@
text
@d2 1
a2 1
.\" $Header: /home1/frew/s2k/postgres/ref/RCS/libpq,v 1.9 1992/03/25 19:25:31 clarsen Exp $
a36 2
.bu
\fBPGOPTION\fR contains optional arguements to the POSTGRES back-end.
@


1.9
log
@async + binary docs
@
text
@d2 2
a3 2
.\" $Header: RCS/libpq,v 1.8 92/01/30 19:39:44 mer Exp Locker: clarsen $
.SS "LIBPQ" 6/14/90
d5 5
d508 2
a509 2
 create test1 (i = int4) \g
 create test1a (i = int4) \g
d515 1
a515 1
 \g
d518 1
a518 1
 append test1 (i = 10) \g
d590 2
a591 2
 create test1 (i = int4,d = float4) \g
 append test1 (i = 7, d=3.567) \g
d650 1
a650 1
.)1@


1.8
log
@PQnames -> PQpnames
@
text
@d2 1
a2 1
.\" $Header: /users/mer/pg_grass/ref/RCS/libpq,v 1.7 1991/11/13 05:20:12 mer Exp mer $
d59 3
a222 5
PQrulep \*- Return 1 if an asynchronous portal.

int PQrulep	(portal)
	PortalBuffer	*portal;

d305 10
d317 30
a346 3
All values are returned
as string.  It is the programmer's responsibility to
convert them to the correct type.
d492 153
@


1.7
log
@better documentation for PQtrace()
@
text
@d2 1
a2 1
.\" $Header: /users/mer/postgres/ref/RCS/libpq,v 1.6 1991/11/12 06:09:09 mer Exp mer $
d201 1
a201 1
PQnames \*- Return all portal names.
d203 1
a203 1
void PQnames  ( pnames, rule_p)
@


1.6
log
@fix copy from stdin example
@
text
@d2 1
a2 1
.\" $Header: /users/mer/postgres/ref/RCS/libpq,v 1.5 1991/08/16 00:32:57 mer Exp mer $
d367 5
@


1.5
log
@version 3.0 updates..... its now a work of art.
@
text
@d2 1
a2 1
.\" $Header: RCS/libpq,v 1.4 91/03/09 05:27:59 kemnitz Exp Locker: mer $
d353 1
a353 1
PQputline("3<TAB>hello world<TAB>4.5");
@


1.4
log
@Added stuff about the copy command.
@
text
@d2 1
a2 1
.\" $Header: RCS/libpq,v 1.3 91/02/25 19:17:21 mike Exp Locker: kemnitz $
d12 1
a12 1
and instances returned through an IPC channel.
d14 2
a15 3
This version of the documentation is based on the C library.  A similar
package exists for Common Lisp.
.uh CONTROL AND INITIALIZATION
a57 2
char	*PQinitstr = NULL; 	/* Initialization string passed to back-end */

d61 1
a61 1
.uh QUERY EXECUTION FUNCTIONS
a64 2
.(l
PQsetdb \*- Make the specified database the current database.
d66 5
a70 1
PQsetdb ( dbname )
d73 2
d77 3
a79 2
	char*	PQdb ()
.)l
d85 2
d88 1
a88 1
PQreset \*- Reset the communication port with the back-end.
d90 1
a90 1
PQreset ()
d92 6
a97 1
Resets communication in case of errors.
d101 1
a101 1
PQfinish ()
d103 1
d107 2
d110 16
d128 1
a128 1
PQexec (query)
d131 1
d133 13
a145 2
This function returns a status indicator or an error message.
.uh PORTAL FUNCTIONS
d164 1
a164 1
portal name is the empty string, known as the "blank portal."
d189 1
a189 1
to issue a retrievel followed by one or more
d199 1
a199 1
If rule_p is not O, then only return the number of asynchronous portals.
d212 1
a212 1
PortalBuffer * PQparray (pname )
d215 5
d236 1
d312 1
a312 1
.uh FUNCTIONS ASSOCIATED WITH THE COPY COMMAND
d316 1
a316 1
command in \*PP has options to read from or write to the network
d337 1
a337 1
PQendcopy() \*- Syncs with the backend.
d347 12
d361 1
a361 1
.uh TRACING FUNCTIONS
a373 7
Only 3 portals can be open at a time.
.lp
IPC glitches between the front-end and the back-end may cause
a query to hang.  When this happens try killing the query with
a keyboard interrupt (^C).  If this does not work, you may have
to kill the process.
.lp
d376 2
a377 1
.uh SAMPLE PROGRAM
a381 1
/*
d395 1
a395 1
    PQsetdb ("Pic-Demo");
d397 3
d410 1
a410 1
	printf ("\nA new instance group:\en");
d431 3
d437 1
a437 1
    printf ("\nNumber of portals open: %d.\en", PQnportals ());
@


1.3
log
@objectified
@
text
@d2 1
a2 1
.\" $Header: RCS/libpq,v 1.2 90/07/20 08:54:39 claire Exp $
d266 37
@


1.2
log
@*** empty log message ***
@
text
@d2 1
a2 1
.\" $Header: RCS/libpq,v 1.1 90/07/18 16:25:41 mao Exp Locker: claire $
d12 1
a12 1
and tuples returned through an IPC channel.
d107 1
a107 1
A portal is a POSTGRES buffer from which tuples can be fetched.
d125 1
a125 1
All qualifying tuples in a blank portal are fetched
d131 1
a131 1
an internal table.  Each tuple in a portal buffer has
d133 1
a133 1
each field in a tuple has a name and a field number.
d136 1
a136 1
of tuples.
d139 1
a139 1
returns multiple record types from an inheritance
d141 1
a141 1
Consequently, the tuples in a portal are set up
d143 2
a144 2
Tuples in the same group are guaranteed to have the
same record format.
d180 1
a180 1
PQntuples \*- Return the number of tuples in a portal buffer.
d185 1
a185 1
PQngroups \*- Return the number of tuple groups in a portal buffer.
d190 1
a190 1
PQntuplesGroup \*- Return the number of tuples in a tuple group.
d195 1
a195 1
PQnfieldsGroup \*- Return the number of fields in a tuple group.
d215 1
a215 1
PQgetgroup \*- Returns the index of the group that a particular tuple is in.
d221 1
a221 1
PQnfields \*- Return the number of fields in a tuple.
d227 1
a227 1
PQfnumber \*- Return the field index of a given field name within a tuple.
d250 1
a250 1
PQsametype \*- Return 1 if two tuples have the same attributes.
d309 1
a309 1
    /* Fetch tuples from the EMP table. */
d313 1
a313 1
    /* Examine all the tuples fetched. */
d319 1
a319 1
	printf ("\nA new tuple group:\en");
d328 1
a328 1
	/* Print out the tuples. */
d342 1
a342 1
    /* Print out the nubmer of portals. */
@


1.1
log
@Initial revision
@
text
@d2 1
a2 1
.\" $Header: libpq,v 1.5 89/03/23 11:51:09 wensel Exp $
d13 1
a13 1
.sp
d16 4
a19 3
.sh 1 "CONTROL AND INITIALIZATION"
.sh 2 "VARIABLES"
.sp
d23 1
a23 1
.sp 1
d36 1
a36 1
.sp
d39 2
a40 1
.sp 1
d62 1
d64 2
a65 3
.sp 1
.sh 1  "QUERY EXECUTION FUNCTIONS"
.sp
d68 1
a68 1

d77 2
a78 1

d83 1
a83 1

d93 2
a94 1

d97 1
a97 1

d102 2
a103 1

d105 2
a106 2
.sh 1 "PORTAL FUNCTIONS"
.sp
d114 1
a114 1
.sp
d122 1
a122 1
.sp
d128 1
a128 1
.sp
d134 1
a134 1
.sp
d145 1
a145 1
.sp
d153 1
a153 2
.nf
.na
d261 2
a262 1

d266 3
a268 2
.sh 1 "TRACING FUNCTIONS"

d276 2
a277 3
.fi
.ad
.sh 1 "BUGS"
d288 3
a290 3

.sh 1 "SAMPLE PROGRAM"

d357 1
a357 1

@