postgresql/src/include/executor/spi.h

/*-------------------------------------------------------------------------
 *
 * spi.h
 *
 * $Id: spi.h,v 1.29 2001/10/25 05:49:59 momjian Exp $
 *
 *-------------------------------------------------------------------------
 */
#ifndef SPI_H
#define SPI_H

/*
 * This file may be used by client modules that haven't already
 * included postgres.h
 */
#include "postgres.h"

/*
 *	These are not needed by this file, but used by other programs
 *	using SPI
 */
#include "nodes/primnodes.h"
#include "nodes/relation.h"
#include "nodes/execnodes.h"
#include "nodes/plannodes.h"
#include "catalog/pg_proc.h"
#include "catalog/pg_type.h"
#include "tcop/pquery.h"
#include "tcop/tcopprot.h"
#include "tcop/utility.h"
#include "tcop/dest.h"
#include "nodes/params.h"
#include "utils/fcache.h"
#include "utils/datum.h"
#include "utils/syscache.h"
#include "utils/builtins.h"
#include "catalog/pg_language.h"
#include "access/heapam.h"
#include "access/xact.h"
#include "executor/executor.h"
#include "executor/execdefs.h"

typedef struct
{
	MemoryContext tuptabcxt;	/* memory context of result table */
	uint32		alloced;		/* # of alloced vals */
	uint32		free;			/* # of free vals */
	TupleDesc	tupdesc;		/* tuple descriptor */
	HeapTuple  *vals;			/* tuples */
} SPITupleTable;

#define SPI_ERROR_CONNECT		(-1)
#define SPI_ERROR_COPY			(-2)
#define SPI_ERROR_OPUNKNOWN		(-3)
#define SPI_ERROR_UNCONNECTED	(-4)
#define SPI_ERROR_CURSOR		(-5)
#define SPI_ERROR_ARGUMENT		(-6)
#define SPI_ERROR_PARAM			(-7)
#define SPI_ERROR_TRANSACTION	(-8)
#define SPI_ERROR_NOATTRIBUTE	(-9)
#define SPI_ERROR_NOOUTFUNC		(-10)
#define SPI_ERROR_TYPUNKNOWN	(-11)

#define SPI_OK_CONNECT			1
#define SPI_OK_FINISH			2
#define SPI_OK_FETCH			3
#define SPI_OK_UTILITY			4
#define SPI_OK_SELECT			5
#define SPI_OK_SELINTO			6
#define SPI_OK_INSERT			7
#define SPI_OK_DELETE			8
#define SPI_OK_UPDATE			9
#define SPI_OK_CURSOR			10

extern DLLIMPORT uint32 SPI_processed;
extern DLLIMPORT Oid SPI_lastoid;
extern DLLIMPORT SPITupleTable *SPI_tuptable;
extern DLLIMPORT int SPI_result;

extern int	SPI_connect(void);
extern int	SPI_finish(void);
extern void SPI_push(void);
extern void SPI_pop(void);
extern int	SPI_exec(char *src, int tcount);
extern int	SPI_execp(void *plan, Datum *values, char *Nulls, int tcount);
extern void *SPI_prepare(char *src, int nargs, Oid *argtypes);
extern void *SPI_saveplan(void *plan);
extern int	SPI_freeplan(void *plan);

extern HeapTuple SPI_copytuple(HeapTuple tuple);
extern TupleDesc SPI_copytupledesc(TupleDesc tupdesc);
extern HeapTuple SPI_modifytuple(Relation rel, HeapTuple tuple, int natts,
				int *attnum, Datum *Values, char *Nulls);
extern int	SPI_fnumber(TupleDesc tupdesc, char *fname);
extern char *SPI_fname(TupleDesc tupdesc, int fnumber);
extern char *SPI_getvalue(HeapTuple tuple, TupleDesc tupdesc, int fnumber);
extern Datum SPI_getbinval(HeapTuple tuple, TupleDesc tupdesc, int fnumber, bool *isnull);
extern char *SPI_gettype(TupleDesc tupdesc, int fnumber);
extern Oid	SPI_gettypeid(TupleDesc tupdesc, int fnumber);
extern char *SPI_getrelname(Relation rel);
extern void *SPI_palloc(Size size);
extern void *SPI_repalloc(void *pointer, Size size);
extern void SPI_pfree(void *pointer);
extern void SPI_freetuple(HeapTuple pointer);
extern void SPI_freetuptable(SPITupleTable *tuptable);

extern Portal SPI_cursor_open(char *name, void *plan,
				Datum *Values, char *Nulls);
extern Portal SPI_cursor_find(char *name);
extern void SPI_cursor_fetch(Portal portal, bool forward, int count);
extern void SPI_cursor_move(Portal portal, bool forward, int count);
extern void SPI_cursor_close(Portal portal);

extern void AtEOXact_SPI(void);
#endif	 /* SPI_H */
SPI manager. 1997-08-29 11:05:57 +02:00			`/*-------------------------------------------------------------------------`
			`*`
Change my-function-name-- to my_function_name, and optimizer renames. 1999-02-14 00:22:53 +01:00			`* spi.h`
Massive commit to run PGINDENT on all .c and .h files. 1997-09-07 07:04:48 +02:00			`*`
pgindent run on all C files. Java run to follow. initdb/regression tests pass. 2001-10-25 07:50:21 +02:00			`* $Id: spi.h,v 1.29 2001/10/25 05:49:59 momjian Exp $`
SPI manager. 1997-08-29 11:05:57 +02:00			`*`
			`*-------------------------------------------------------------------------`
			`*/`
Massive commit to run PGINDENT on all .c and .h files. 1997-09-07 07:04:48 +02:00			`#ifndef SPI_H`
SPI manager. 1997-08-29 11:05:57 +02:00			`#define SPI_H`

Restructure the key include files per recent pghackers discussion: there are now separate files "postgres.h" and "postgres_fe.h", which are meant to be the primary include files for backend .c files and frontend .c files respectively. By default, only include files meant for frontend use are installed into the installation include directory. There is a new make target 'make install-all-headers' that adds the whole content of the src/include tree to the installed fileset, for use by people who want to develop server-side code without keeping the complete source tree on hand. Cleaned up a whole lot of crufty and inconsistent header inclusions. 2001-02-10 03:31:31 +01:00			`/*`
			`* This file may be used by client modules that haven't already`
			`* included postgres.h`
			`*/`
SPI manager. 1997-08-29 11:05:57 +02:00			`#include "postgres.h"`
Clean up #include in /include directory. Add scripts for checking includes. 1999-07-15 17:21:54 +02:00
			`/*`
			`* These are not needed by this file, but used by other programs`
			`* using SPI`
			`*/`
SPI manager. 1997-08-29 11:05:57 +02:00			`#include "nodes/primnodes.h"`
			`#include "nodes/relation.h"`
			`#include "nodes/execnodes.h"`
			`#include "nodes/plannodes.h"`
			`#include "catalog/pg_proc.h"`
Add pg_type.h to include list to regain declaration of type OID assignments. Lost these when some include files were reorganized. Regression test could not compile. 1997-11-30 23:42:58 +01:00			`#include "catalog/pg_type.h"`
SPI manager. 1997-08-29 11:05:57 +02:00			`#include "tcop/pquery.h"`
			`#include "tcop/tcopprot.h"`
			`#include "tcop/utility.h"`
			`#include "tcop/dest.h"`
			`#include "nodes/params.h"`
			`#include "utils/fcache.h"`
			`#include "utils/datum.h"`
			`#include "utils/syscache.h"`
Cleanups. 1997-09-11 09:24:37 +02:00			`#include "utils/builtins.h"`
SPI manager. 1997-08-29 11:05:57 +02:00			`#include "catalog/pg_language.h"`
			`#include "access/heapam.h"`
			`#include "access/xact.h"`
			`#include "executor/executor.h"`
			`#include "executor/execdefs.h"`

Massive commit to run PGINDENT on all .c and .h files. 1997-09-07 07:04:48 +02:00			`typedef struct`
			`{`
Enhancement of SPI to get access to portals - New functions to create a portal using a prepared/saved SPI plan or lookup an existing portal by name. - Functions to fetch/move from/in portals. Results are placed in the usual SPI_processed and SPI_tuptable, so the entire set of utility functions can be used to gain attribute access. - Prepared/saved SPI plans now use their own memory context and SPI_freeplan(plan) can remove them. - Tuple result sets (SPI_tuptable) now uses it's own memory context and can be free'd by SPI_freetuptable(tuptab). Enhancement of PL/pgSQL - Uses generic named portals internally in FOR ... SELECT loops to avoid running out of memory on huge result sets. - Support for CURSOR and REFCURSOR syntax using the new SPI functionality. Cursors used internally only need no explicit transaction block. Refcursor variables can be used inside of explicit transaction block to pass cursors between main application and functions. Jan 2001-05-21 16:22:19 +02:00			`MemoryContext tuptabcxt; /* memory context of result table */`
Another PGINDENT run that changes variable indenting and case label indenting. Also static variable indenting. 1997-09-08 04:41:22 +02:00			`uint32 alloced; /* # of alloced vals */`
			`uint32 free; /* # of free vals */`
			`TupleDesc tupdesc; /* tuple descriptor */`
			`HeapTuple vals; / tuples */`
pgindent run before 6.3 release, with Thomas' requested changes. 1998-02-26 05:46:47 +01:00			`} SPITupleTable;`
SPI manager. 1997-08-29 11:05:57 +02:00
Add a SPI_copytupledesc function that parallels SPI_copytuple --- ie, it copies the tupdesc into upper-executor memory. This is necessary for returning tuple descriptors without leaking all of lower exec memory. 2001-08-02 20:08:43 +02:00			`#define SPI_ERROR_CONNECT (-1)`
			`#define SPI_ERROR_COPY (-2)`
			`#define SPI_ERROR_OPUNKNOWN (-3)`
			`#define SPI_ERROR_UNCONNECTED (-4)`
			`#define SPI_ERROR_CURSOR (-5)`
			`#define SPI_ERROR_ARGUMENT (-6)`
			`#define SPI_ERROR_PARAM (-7)`
			`#define SPI_ERROR_TRANSACTION (-8)`
			`#define SPI_ERROR_NOATTRIBUTE (-9)`
			`#define SPI_ERROR_NOOUTFUNC (-10)`
			`#define SPI_ERROR_TYPUNKNOWN (-11)`
SPI manager. 1997-08-29 11:05:57 +02:00
Massive commit to run PGINDENT on all .c and .h files. 1997-09-07 07:04:48 +02:00			`#define SPI_OK_CONNECT 1`
			`#define SPI_OK_FINISH 2`
			`#define SPI_OK_FETCH 3`
			`#define SPI_OK_UTILITY 4`
			`#define SPI_OK_SELECT 5`
			`#define SPI_OK_SELINTO 6`
			`#define SPI_OK_INSERT 7`
			`#define SPI_OK_DELETE 8`
			`#define SPI_OK_UPDATE 9`
			`#define SPI_OK_CURSOR 10`
Prototypes, definitions... 1997-09-04 15:26:19 +02:00
Changes to fix/improve the dynamic loading on NT From: Horak Daniel <horak@mmp.plzen-city.cz> 1999-03-09 14:39:15 +01:00			`extern DLLIMPORT uint32 SPI_processed;`
Change plpgsql's GET DIAGNOSTICS statement to use SQL99-compatible syntax. Fix the RESULT_OID case, which never worked. Add documentation. 2001-02-19 20:49:53 +01:00			`extern DLLIMPORT Oid SPI_lastoid;`
Changes to fix/improve the dynamic loading on NT From: Horak Daniel <horak@mmp.plzen-city.cz> 1999-03-09 14:39:15 +01:00			`extern DLLIMPORT SPITupleTable *SPI_tuptable;`
pgindent run over code. 1999-05-25 18:15:34 +02:00			`extern DLLIMPORT int SPI_result;`
SPI manager. 1997-08-29 11:05:57 +02:00
Another PGINDENT run that changes variable indenting and case label indenting. Also static variable indenting. 1997-09-08 04:41:22 +02:00			`extern int SPI_connect(void);`
			`extern int SPI_finish(void);`
pgindent run over code. 1999-05-25 18:15:34 +02:00			`extern void SPI_push(void);`
			`extern void SPI_pop(void);`
Another PGINDENT run that changes variable indenting and case label indenting. Also static variable indenting. 1997-09-08 04:41:22 +02:00			`extern int SPI_exec(char *src, int tcount);`
pgindent run before 6.3 release, with Thomas' requested changes. 1998-02-26 05:46:47 +01:00			`extern int SPI_execp(void plan, Datum values, char *Nulls, int tcount);`
			`extern void SPI_prepare(char src, int nargs, Oid *argtypes);`
Another PGINDENT run that changes variable indenting and case label indenting. Also static variable indenting. 1997-09-08 04:41:22 +02:00			`extern void SPI_saveplan(void plan);`
pgindent run on all C files. Java run to follow. initdb/regression tests pass. 2001-10-25 07:50:21 +02:00			`extern int SPI_freeplan(void *plan);`
Prototypes, definitions... 1997-09-04 15:26:19 +02:00
Added: SPI_copytuple() & SPI_modifytuple() 1997-09-12 10:37:52 +02:00			`extern HeapTuple SPI_copytuple(HeapTuple tuple);`
Add a SPI_copytupledesc function that parallels SPI_copytuple --- ie, it copies the tupdesc into upper-executor memory. This is necessary for returning tuple descriptors without leaking all of lower exec memory. 2001-08-02 20:08:43 +02:00			`extern TupleDesc SPI_copytupledesc(TupleDesc tupdesc);`
OK, folks, here is the pgindent output. 1998-09-01 06:40:42 +02:00			`extern HeapTuple SPI_modifytuple(Relation rel, HeapTuple tuple, int natts,`
pgindent run before 6.3 release, with Thomas' requested changes. 1998-02-26 05:46:47 +01:00			`int attnum, Datum Values, char *Nulls);`
Another PGINDENT run that changes variable indenting and case label indenting. Also static variable indenting. 1997-09-08 04:41:22 +02:00			`extern int SPI_fnumber(TupleDesc tupdesc, char *fname);`
Cleanups. 1997-09-11 09:24:37 +02:00			`extern char *SPI_fname(TupleDesc tupdesc, int fnumber);`
Another PGINDENT run that changes variable indenting and case label indenting. Also static variable indenting. 1997-09-08 04:41:22 +02:00			`extern char *SPI_getvalue(HeapTuple tuple, TupleDesc tupdesc, int fnumber);`
pgindent run before 6.3 release, with Thomas' requested changes. 1998-02-26 05:46:47 +01:00			`extern Datum SPI_getbinval(HeapTuple tuple, TupleDesc tupdesc, int fnumber, bool *isnull);`
Another PGINDENT run that changes variable indenting and case label indenting. Also static variable indenting. 1997-09-08 04:41:22 +02:00			`extern char *SPI_gettype(TupleDesc tupdesc, int fnumber);`
			`extern Oid SPI_gettypeid(TupleDesc tupdesc, int fnumber);`
			`extern char *SPI_getrelname(Relation rel);`
pgindent run before 6.3 release, with Thomas' requested changes. 1998-02-26 05:46:47 +01:00			`extern void *SPI_palloc(Size size);`
			`extern void SPI_repalloc(void pointer, Size size);`
			`extern void SPI_pfree(void *pointer);`
Some changes to prepare for LONG attributes. Jan 1999-12-16 23:20:03 +01:00			`extern void SPI_freetuple(HeapTuple pointer);`
Enhancement of SPI to get access to portals - New functions to create a portal using a prepared/saved SPI plan or lookup an existing portal by name. - Functions to fetch/move from/in portals. Results are placed in the usual SPI_processed and SPI_tuptable, so the entire set of utility functions can be used to gain attribute access. - Prepared/saved SPI plans now use their own memory context and SPI_freeplan(plan) can remove them. - Tuple result sets (SPI_tuptable) now uses it's own memory context and can be free'd by SPI_freetuptable(tuptab). Enhancement of PL/pgSQL - Uses generic named portals internally in FOR ... SELECT loops to avoid running out of memory on huge result sets. - Support for CURSOR and REFCURSOR syntax using the new SPI functionality. Cursors used internally only need no explicit transaction block. Refcursor variables can be used inside of explicit transaction block to pass cursors between main application and functions. Jan 2001-05-21 16:22:19 +02:00			`extern void SPI_freetuptable(SPITupleTable *tuptable);`

pgindent run on all C files. Java run to follow. initdb/regression tests pass. 2001-10-25 07:50:21 +02:00			`extern Portal SPI_cursor_open(char name, void plan,`
Enhancement of SPI to get access to portals - New functions to create a portal using a prepared/saved SPI plan or lookup an existing portal by name. - Functions to fetch/move from/in portals. Results are placed in the usual SPI_processed and SPI_tuptable, so the entire set of utility functions can be used to gain attribute access. - Prepared/saved SPI plans now use their own memory context and SPI_freeplan(plan) can remove them. - Tuple result sets (SPI_tuptable) now uses it's own memory context and can be free'd by SPI_freetuptable(tuptab). Enhancement of PL/pgSQL - Uses generic named portals internally in FOR ... SELECT loops to avoid running out of memory on huge result sets. - Support for CURSOR and REFCURSOR syntax using the new SPI functionality. Cursors used internally only need no explicit transaction block. Refcursor variables can be used inside of explicit transaction block to pass cursors between main application and functions. Jan 2001-05-21 16:22:19 +02:00			`Datum Values, char Nulls);`
			`extern Portal SPI_cursor_find(char *name);`
pgindent run on all C files. Java run to follow. initdb/regression tests pass. 2001-10-25 07:50:21 +02:00			`extern void SPI_cursor_fetch(Portal portal, bool forward, int count);`
			`extern void SPI_cursor_move(Portal portal, bool forward, int count);`
			`extern void SPI_cursor_close(Portal portal);`
SPI manager. 1997-08-29 11:05:57 +02:00
First phase of memory management rewrite (see backend/utils/mmgr/README for details). It doesn't really do that much yet, since there are no short-term memory contexts in the executor, but the infrastructure is in place and long-term contexts are handled reasonably. A few long- standing bugs have been fixed, such as 'VACUUM; anything' in a single query string crashing. Also, out-of-memory is now considered a recoverable ERROR, not FATAL. Eliminate a large amount of crufty, now-dead code in and around memory management. Fix problem with holding off SIGTRAP, SIGSEGV, etc in postmaster and backend startup. 2000-06-28 05:33:33 +02:00			`extern void AtEOXact_SPI(void);`
OK, folks, here is the pgindent output. 1998-09-01 06:40:42 +02:00			`#endif /* SPI_H */`