Programming Guide

STORE

Sets up a continuation file for a named or default cursor

Synopsis

DBMS [WITH CURSOR cursor] STORE [FILE [filename]]

Arguments

WITH CURSOR cursor
Name of declared SELECT cursor. If the clause is not used, Panther uses the default SELECT cursor.

filename
Name of temporary binary file.

Description

When DBMS STORE is used with a SELECT cursor, Panther maintains a copy of the result rows in a temporary binary file. The file permits an application to scroll forward and backward in a select set, even if the database has no native support for backward scrolling.

A continuation file remains open for the life of the cursor, or until the feature is turned off with the command, 

DBMS [WITH CURSOR cursor] STORE

Executing the command without the keyword FILE closes and deletes the file and turns off the feature for the named or default cursor. Closing the cursor also closes and deletes the file. If a cursor is not closed but simply redeclared for another SELECT statement, the file is cleared. Therefore, a continuation file holds the results of one SELECT statement only.

The use of a continuation file does not force the database engine to return the entire select set when the SELECT is executed. Panther examines the number of occurrences in the destination variable to determine the number of rows to fetch. Each time it fetches rows from the database engine by executing the SELECT or a CONTINUE, Panther updates the screen and appends the new data to the continuation file. If the application wishes to see rows already fetched, Panther uses the continuation file to get the rows and update the screen. If Panther reaches the end of the continuation file and the application executes another DBMS CONTINUE, Panther attempts to get more rows from the database engine. When the engine returns the no-more-rows code, Panther sets @dmretcode to the value of DM_NO_MORE_ROWS. Similarly, if the application attempts to scroll back past the first row in the continuation file, Panther sets @dmretcode to DM_NO_MORE_ROWS. Write errors are not reported.

DBMS STORE provides several advantages:

For information on engine-specific scrolling issues, refer to "Database Drivers."

Example

// Use of STORE FILE with JPL procedures to fetch more rows.
 
proc title_select
	DBMS DECLARE t_cursor CURSOR FOR SELECT * FROM titles
	DBMS WITH CURSOR t_cursor STORE FILE
	DBMS WITH CURSOR t_cursor EXECUTE
	return
 
proc get_next
	DBMS WITH CURSOR t_cursor CONTINUE_DOWN
	return
 
proc get_previous
	DBMS WITH CURSOR t_cursor CONTINUE_UP
	return
 
// Use of STORE FILE and map keys in order to fetch more rows.
 
proc select_titles
	DBMS DECLARE t_cursor CURSOR FOR SELECT * FROM titles
	DBMS WITH CURSOR t_cursor STORE FILE
	DBMS WITH CURSOR t_cursor EXECUTE
	return
 
// This procedure is called on screen entry.
 
proc entry (name, flag)
if (flag & K_ENTRY)
{
	call sm_keyoption (SPGD, KEY_XLATE, APP1)
	call sm_keyoption (SPGU, KEY_XLATE, APP2)
}
...
return
 
//This procedure is called on screen exit.
 
proc exit (name, flag)
if (flag & K_EXIT)
{
	call sm_keyoption (SPGU, KEY_XLATE, SPGU)
	call sm_keyoption (SPGD, KEY_XLATE, SPGD)
}
...
return
 
proc scroll_up
// Control strings contains:
// APP1 = ^scroll_up 
	DBMS WITH CURSOR t_cursor CONTINUE_UP
	return
 
proc scroll_down
// Control strings contains:
// APP2 = ^scroll_down
	DBMS WITH CURSOR t_cursor CONTINUE
	return

See Also

CONTINUE