list_open2

Opens a list.

Available in:

Apps (win) Apps (char) Reportwriter RPC Standalone PL
X X X X X

Syntax

list list_open2(stmt,limit[,parm[,...]])
expr            stmt
int             limit
expr            parm

Description

Creates a list and loads it with rows. The current item pointer is set to the first item in the list. All items in the list are set to item_select status. list_open2 differs from list_open in several respects:
limit specifies the maximum number of rows that can be loaded into the new list. If this parameter is -1, the function executes a SQL DESCRIBE with the resulting list containing the column information.

stmt must be a select statement. Anything else returns an error. Statement parameters are specified in either "?" or ":n" format depending upon the target database. stmt can be a constant or variable string however it is always treated as a dynamic statement. It is processed as follows:
  1. If the trim.ini/dv.ini dynamic_cursors value is not set or set to 0 or the dynamic cursor cache is full, then the stmt is not cached and is hard closed when the list is closed.
  2. If the stmt matches an existing dynamic cursor cache statement
    1. If the cached statement is soft closed, then list_open2 uses that cursor.
    2. If the cached statement is not soft closed, then list_open2 follows step 1.
  3. If the stmt does not match an existing dynamic cursor cache statement and the cache is not full, then list_open2 creates a new dynamic cached statement.
parmparameters used for any parameter markers in the select statement. Parameters can be individual variables except for lists, constants, parm.n, parm[n] or parm().

Notes

The sysinfo(sysinfo_dyncurs) returns information about the dynamic cursor cache.

Examples

Execute a DESCRIBE on the table. 
xx = list_open("SELECT * FROM " ^^ tname,-1);
Load a list from the database. 
xx = list_open("SELECT * FROM staff where id = ?",1000,10);
Load a list from the database with multiple parameters. 
xx = list_open("SELECT * FROM staff where id = ? and name like ? and salary < ?",1000,10,parm(2,2));