portal.c

关系型数据库 Postgresql 6.5.2

/*-------------------------------------------------------------------------
 *
 * portal.c
 *	  generalized portal support routines
 *
 * Copyright (c) 1994, Regents of the University of California
 *
 *	$Id: portal.c,v 1.22 1999/05/25 16:09:01 momjian Exp $
 *
 *-------------------------------------------------------------------------
 */
/*
 *	 INTERFACE ROUTINES
 *		PQnportals		- Return the number of open portals.
 *		PQpnames		- Return all the portal names
 *		PQparray		- Return the portal buffer given a portal name
 *		PQrulep			- Return 1 if an asynchronous portal
 *		PQntuples		- Return the number of tuples in a portal buffer
 *		PQninstances	-	same as PQntuples using object terminology
 *		PQngroups		- Return the number of tuple groups in a portal buffer
 *		PQntuplesGroup	- Return the number of tuples in a tuple group
 *		PQninstancesGroup  - same as PQntuplesGroup using object terminology
 *		PQnfieldsGroup	- Return the number of fields in a tuple group
 *		PQfnumberGroup	- Return field number given (group index, field name)
 *		PQftypeGroup	- Return field type given (group index, field index)
 *		PQfsizeGroup	- Return field size given (group index, field index)
 *		PQfnameGroup	- Return field name given (group index, field index)
 *		PQgroup			- Return the tuple group that a particular tuple is in
 *		PQgetgroup		- Return the index of the group that a tuple is in
 *		PQnfields		- Return the number of fields in a tuple
 *		PQfnumber		- Return the field index of a field name in a tuple
 *		PQfname			- Return the name of a field
 *		PQftype			- Return the type of a field
 *		PQfsize			- Return the size of a field
 *		PQftype			- Return the type of a field
 *		PQsametype		- Return 1 if the two tuples have the same type
 *		PQgetvalue		- Return an attribute (field) value
 *		PQgetlength		- Return an attribute (field) length
 *		PQclear			- free storage claimed by named portal
 *
 *	 NOTES
 *		These functions may be used by both frontend routines which
 *		communicate with a backend or by user-defined functions which
 *		are compiled or dynamically loaded into a backend.
 *
 *		the *portals array should be organized as a hash table for
 *		quick portal-by-name lookup.
 *
 *		Do not confuse "PortalEntry" (or "PortalBuffer") with "Portal"
 *		see utils/mmgr/portalmem.c for why. -cim 2/22/91
 *
 */
#include <stdio.h>
#include <string.h>

#include <postgres.h>

#include <lib/dllist.h>
#include <libpq/libpq.h>		/* where the declarations go */
#include <utils/exc.h>


/* ----------------------------------------------------------------
 *	  Helper routines for PQ portal interface routines below
 * ----------------------------------------------------------------
 */

static int
in_range(char *msg, int value, int min, int max)
{
	if (value < min || value >= max)
	{
		snprintf(PQerrormsg, ERROR_MSG_LENGTH,
		"FATAL: %s, %d is not in range [%d,%d)\n", msg, value, min, max);
		pqdebug("%s", PQerrormsg);
		fputs(PQerrormsg, stderr);
		return 0;
	}
	return 1;
}

static int
valid_pointer(char *msg, void *ptr)
{
	if (!ptr)
	{
		snprintf(PQerrormsg, ERROR_MSG_LENGTH, "FATAL: %s\n", msg);
		pqdebug("%s", PQerrormsg);
		fputs(PQerrormsg, stderr);
		return 0;
	}
	return 1;
}


/* ----------------------------------------------------------------
 *					PQ portal interface routines
 * ----------------------------------------------------------------
 */

/* --------------------------------
 *		PQnportals - Return the number of open portals.
 *		If rule_p, only return asynchronous portals.
 * --------------------------------
 */
int
PQnportals(int rule_p)
{
	int			i,
				n = 0;

	for (i = 0; i < portals_array_size; ++i)
	{
		if (portals[i] && portals[i]->portal)
		{
			if (!rule_p || portals[i]->portal->rule_p)
				++n;
		}
	}
	return n;
}

/* --------------------------------
 *		PQpnames - Return all the portal names
 *		If rule_p, only return asynchronous portals.
 *
 *		   the caller must have allocated sufficient memory for char** pnames
 *		   (an array of PQnportals strings of length PortalNameLength).
 *
 *		   notice that this assumes that the user is calling PQnportals and
 *		   PQpnames with the same rule_p argument, and with no intervening
 *		   portal closures.  if not, you can get in heap big trouble..
 * --------------------------------
 */
void
PQpnames(char **pnames, int rule_p)
{
	int			i,
				cur_pname = 0;

	if (!valid_pointer("PQpnames: invalid name buffer", pnames))
		return;

	for (i = 0; i < portals_array_size; ++i)
	{
		if (portals[i] && portals[i]->portal)
		{
			if (!rule_p || portals[i]->portal->rule_p)
			{
				strncpy(pnames[cur_pname], portals[i]->name, PortalNameLength + 1);
				++cur_pname;
			}
		}
	}
}

/* --------------------------------
 *		PQparray - Return the portal buffer given a portal name
 * --------------------------------
 */
PortalBuffer *
PQparray(char *pname)
{
	int			i;

	if (!valid_pointer("PQparray: invalid name buffer", pname))
		return NULL;

	if ((i = pbuf_getIndex(pname)) < 0)
		return (PortalBuffer *) NULL;
	return portals[i]->portal;
}

/* --------------------------------
 *		PQrulep - Return 1 if an asynchronous portal
 * --------------------------------
 */
int
PQrulep(PortalBuffer *portal)
{
	if (!valid_pointer("PQrulep: invalid portal pointer", portal))
		return -1;

	return portal->rule_p;
}

/* --------------------------------
 *		PQntuples - Return the number of tuples in a portal buffer
 * --------------------------------
 */
int
PQntuples(PortalBuffer *portal)
{
	if (!valid_pointer("PQntuples: invalid portal pointer", portal))
		return -1;

	return portal->no_tuples;
}

int
PQninstances(PortalBuffer *portal)
{
	return PQntuples(portal);
}

/* --------------------------------
 *		PQngroups - Return the number of tuple groups in a portal buffer
 * --------------------------------
 */
int
PQngroups(PortalBuffer *portal)
{
	if (!valid_pointer("PQngroups: invalid portal pointer", portal))
		return -1;

	return portal->no_groups;
}

/* --------------------------------
 *		PQntuplesGroup - Return the number of tuples in a tuple group
 * --------------------------------
 */
int
PQntuplesGroup(PortalBuffer *portal, int group_index)
{
	GroupBuffer *gbp;

	if (!valid_pointer("PQntuplesGroup: invalid portal pointer", portal) ||
		!in_range("PQntuplesGroup: group index",
				  group_index, 0, portal->no_groups))
		return -1;

	gbp = pbuf_findGroup(portal, group_index);
	if (gbp)
		return gbp->no_tuples;
	return -1;
}

int
PQninstancesGroup(PortalBuffer *portal, int group_index)
{
	return PQntuplesGroup(portal, group_index);
}

/* --------------------------------
 *		PQnfieldsGroup - Return the number of fields in a tuple group
 * --------------------------------
 */
int
PQnfieldsGroup(PortalBuffer *portal, int group_index)
{
	GroupBuffer *gbp;

	if (!valid_pointer("PQnfieldsGroup: invalid portal pointer", portal) ||
		!in_range("PQnfieldsGroup: group index",
				  group_index, 0, portal->no_groups))
		return -1;
	gbp = pbuf_findGroup(portal, group_index);
	if (gbp)
		return gbp->no_fields;
	return -1;
}

/* --------------------------------
 *		PQfnumberGroup - Return the field number (index) given
 *						 the group index and the field name
 * --------------------------------
 */
int
PQfnumberGroup(PortalBuffer *portal, int group_index, char *field_name)
{
	GroupBuffer *gbp;

	if (!valid_pointer("PQfnumberGroup: invalid portal pointer", portal) ||
		!valid_pointer("PQfnumberGroup: invalid field name pointer",
					   field_name) ||
		!in_range("PQfnumberGroup: group index",
				  group_index, 0, portal->no_groups))
		return -1;
	gbp = pbuf_findGroup(portal, group_index);
	if (gbp)
		return pbuf_findFnumber(gbp, field_name);
	return -1;
}

/* --------------------------------
 *		PQfnameGroup - Return the field (attribute) name given
 *						the group index and field index.
 * --------------------------------
 */
char *
PQfnameGroup(PortalBuffer *portal, int group_index, int field_number)
{
	GroupBuffer *gbp;

	if (!valid_pointer("PQfnameGroup: invalid portal pointer", portal) ||
		!in_range("PQfnameGroup: group index",
				  group_index, 0, portal->no_groups))
		return (char *) NULL;

	if ((gbp = pbuf_findGroup(portal, group_index)) &&
		in_range("PQfnameGroup: field number",
				 field_number, 0, gbp->no_fields))
		return pbuf_findFname(gbp, field_number);
	return (char *) NULL;
}

/* --------------------------------
 *		PQftypeGroup - Return the type of a field given
 *						the group index and field index
 * --------------------------------
 */
int
PQftypeGroup(PortalBuffer *portal, int group_index, int field_number)
{
	GroupBuffer *gbp;

	if (!valid_pointer("PQftypeGroup: invalid portal pointer", portal) ||
		!in_range("PQftypeGroup: group index",
				  group_index, 0, portal->no_groups))
		return -1;

	if ((gbp = pbuf_findGroup(portal, group_index)) &&
		in_range("PQftypeGroup: field number", field_number, 0, gbp->no_fields))