This patch implements holdable cursors, following the proposal

(materialization into a tuple store) discussed on pgsql-hackers earlier.
I've updated the documentation and the regression tests.

Notes on the implementation:

- I needed to change the tuple store API slightly -- it assumes that it
won't be used to hold data across transaction boundaries, so the temp
files that it uses for on-disk storage are automatically reclaimed at
end-of-transaction. I added a flag to tuplestore_begin_heap() to control
this behavior. Is changing the tuple store API in this fashion OK?

- in order to store executor results in a tuple store, I added a new
CommandDest. This works well for the most part, with one exception: the
current DestFunction API doesn't provide enough information to allow the
Executor to store results into an arbitrary tuple store (where the
particular tuple store to use is chosen by the call site of
ExecutorRun). To workaround this, I've temporarily hacked up a solution
that works, but is not ideal: since the receiveTuple DestFunction is
passed the portal name, we can use that to lookup the Portal data
structure for the cursor and then use that to get at the tuple store the
Portal is using. This unnecessarily ties the Portal code with the
tupleReceiver code, but it works...

The proper fix for this is probably to change the DestFunction API --
Tom suggested passing the full QueryDesc to the receiveTuple function.
In that case, callers of ExecutorRun could "subclass" QueryDesc to add
any additional fields that their particular CommandDest needed to get
access to. This approach would work, but I'd like to think about it for
a little bit longer before deciding which route to go. In the mean time,
the code works fine, so I don't think a fix is urgent.

- (semi-related) I added a NO SCROLL keyword to DECLARE CURSOR, and
adjusted the behavior of SCROLL in accordance with the discussion on
-hackers.

- (unrelated) Cleaned up some SGML markup in sql.sgml, copy.sgml

Neil Conway

src/backend/storage/file/fd.c

@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1994, Regents of the University of California
  *
  * IDENTIFICATION
- *	  $Header: /cvsroot/pgsql/src/backend/storage/file/fd.c,v 1.95 2002/09/02 06:11:42 momjian Exp $
+ *	  $Header: /cvsroot/pgsql/src/backend/storage/file/fd.c,v 1.96 2003/03/27 16:51:29 momjian Exp $
  *
  * NOTES:
  *
@@ -112,14 +112,14 @@ int			max_files_per_process = 1000;
 
 #define FileUnknownPos (-1L)
 
+/* these are the assigned bits in fdstate below: */
+#define FD_TEMPORARY		(1 << 0)
+#define FD_TXN_TEMPORARY	(1 << 1)
+
 typedef struct vfd
 {
 	signed short fd;			/* current FD, or VFD_CLOSED if none */
 	unsigned short fdstate;		/* bitflags for VFD's state */
-
-/* these are the assigned bits in fdstate: */
-#define FD_TEMPORARY	(1 << 0)	/* should be unlinked when closed */
-
 	File		nextFree;		/* link to next free VFD, if in freelist */
 	File		lruMoreRecently;	/* doubly linked recency-of-use list */
 	File		lruLessRecently;
@@ -750,9 +750,15 @@ PathNameOpenFile(FileName fileName, int fileFlags, int fileMode)
  * This routine takes care of generating an appropriate tempfile name.
  * There's no need to pass in fileFlags or fileMode either, since only
  * one setting makes any sense for a temp file.
+ *
+ * keepOverTxn: if true, don't close the file at end-of-transaction. In
+ * most cases, you don't want temporary files to outlive the transaction
+ * that created them, so this should be false -- but if you need
+ * "somewhat" temporary storage, this might be useful. In either case,
+ * the file is removed when the File is explicitely closed.
  */
 File
-OpenTemporaryFile(void)
+OpenTemporaryFile(bool keepOverTxn)
 {
 	char		tempfilepath[128];
 	File		file;
@@ -795,9 +801,13 @@ OpenTemporaryFile(void)
 			elog(ERROR, "Failed to create temporary file %s", tempfilepath);
 	}
 
-	/* Mark it for deletion at close or EOXact */
+	/* Mark it for deletion at close */
 	VfdCache[file].fdstate |= FD_TEMPORARY;
 
+	/* Mark it for deletion at EOXact */
+	if (!keepOverTxn)
+		VfdCache[file].fdstate |= FD_TXN_TEMPORARY;
+
 	return file;
 }
 
@@ -1114,6 +1124,7 @@ AtEOXact_Files(void)
 		for (i = 1; i < SizeVfdCache; i++)
 		{
 			if ((VfdCache[i].fdstate & FD_TEMPORARY) &&
+				(VfdCache[i].fdstate & FD_TXN_TEMPORARY) &&
 				VfdCache[i].fileName != NULL)
 				FileClose(i);
 		}