list_open

Opens a list.

Available in:

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

Syntax

list list_open(spec,limit[,title[,...]])
expr           spec
int            limit
string         title

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.
limit specifies the maximum number of rows that can be loaded into the new list. If spec is a SELECT, and this parameter is -1, the function executes a SQL DESCRIBE with the resulting list containing the column information.

spec can be a:
  • SELECT statement -- The statement must begin with one of the following keywords: 'SELECT ' followed by the rest of the statement, 'SQL ' followed by a valid SQL SELECT statement, or 'D ' (not case sensitive) followed by a valid SELECT statement. If spec is a constant string, then it is scanned during trimgen for runtime bind variables which are indicated using &varname or &/function()/. list_open() executes the statement and loads the list with the data returned from the database. Constant spec statements are cached for future reuse. Dynamic spec statements, either variables or concatenated within the list_open() call are not cached unless they begin with 'D ' and the dynamic_cursors keyword is specified as non-zero in dv.ini/trim.ini.
  • file name -- Whenever a file name is specified the extended file names are available. Be sure to give a complete file specification.
    Files can be one of four types: ascii (one column), binary (formatted by list_file), JSON, or XML. list_open attempts to determine the file structure by examining the first few characters of the file. If you know the file type, you can skip this process by prepending the file name with 'A ' for ascii, 'B ' for binary, 'J ' for JSON, or 'X ' for XML.
    The file type can be enclosed within square brackets "[]". For example, "[J] filename" is equivalent to "J filename". The bracket form is used to pass in additional file type handling options. Currently these exist only for JSON files and the only option is "I2N", for example "[J I2N] filename". This means that Integer values are to be converted to Numeric when put in the list.
  • s list-name -- Considered a shared list. TRIMpl looks in the index file specified by the TRIM_SHM_FILE environment variable to find the memory address of the shared list identified by list-name. The list must have been previously filed as a shared list.
  • Definition -- Begins with a digit. A definition consists of a list of numbers that represents the display width of the columns. No data is loaded.
  • Control List -- Can be edi, variable or fixed.

EDI Control List Format

Item Content Description Example
0 filename [logfile] Name of file to open, Optional log file "myedi.txt"
1 edi Indicates EDIFACT ISO ISO9735 format edi
2 S S- Default record separator character '

Variable Control List Format

Item Content Description Example
0 filename [logfile] Name of file to open, Optional log file "/tmp/test.exp mylog.txt"
1 variable Indicates variable format variable
2 S[E] [N] S - Separator character
E - Optional enclosing character
N - String indicating a NULL
,' NULL
3 - n D [F] D - Datatype (C,D,I,N) see datatype()
F - Format mask
D YY/MM/DD

Fixed Control List Format

Item Content Description Example
0 filename [logfile] Name of file to open, Optional log file "/tmp/test.exp "
1 fixed Indicates fixed format fixed
2 [N] N - String indicating a NULL NULL
3 - n D O L [F] D - Datatype (C,D,I,N) see datatype()
O - Column offset (0 based)
L - Column length
F - Format mask
N 0 10 99,999.99
In fixed format files or un-enclosed columns, leading and trailing blanks are stripped. If you specify a logfile then lines that do not conform to the specification are logged to this file. Otherwise an error is triggered.

Note that control lists can only have one column. You specify these columns as strings, enclosed by quotes, and separate the elements with spaces.

title specifies the title that appears at the top of the list box during list_view operations.

Sybase

Sybase stored procedures can return a result list by using list_open():
ll = list_open("select_procedure-name [&parm1 &parm2 ...]",...)
For example, staff2 is a stored procedure defined as:
create procedure staff2 @p1 integer as
SELECT * FROM staff WHERE id > @p1
To return the first 20 rows where id > 42:
int id;
id = 42;
ll = list_open("select_staff2 &id",20);

Examples

Execute a DESCRIBE on the table.
xx = list_open("SELECT * FROM " ^^ tname,-1,tname);
Load a list from the database.
xx = list_open("SELECT * FROM emp",1000,"All employees");
Define a list.
xx = list_open("20 16 10",1000,"Beers of the world");
Load a list from a file.
xx = list_open("/etc/passwd",1000,"Users","(from passwd file)");
Load a binary list from a file.
xx = list_open("mylist",1000,"Sales information");
or
xx = list_open("B mylist",1000,"Sales information");
Load a previously stored shared list.
xx = list_open("s zipcode",1000,"Zip Codes of USA");
The following example loads a delimited file into a list. This code is part of an application that loads a FTP logfile into a list where it is processed for database entry.
  int      i;
  list     CL, LL, NL;
  datetime dt;
  char     buf[80], host [160];

/* building the spec  */

  list_mod(CL, 1, "xferlog");
  list_mod(CL, 1, "variable");
  list_mod(CL, 1, " ");
  list_mod(CL, 1, "C");          /* 0 -- day of week */
  list_mod(CL, 1, "C");          /* 1 -- month       */
  list_mod(CL, 1, "C");          /* 2 -- day         */
  list_mod(CL, 1, "C");          /* 3 -- time        */
  list_mod(CL, 1, "C");          /* 4 -- year        */
  list_mod(CL, 1, "N");          /* 5 -- transfer time */
  list_mod(CL, 1, "C");          /* 6 -- host        */
  list_mod(CL, 1, "N");          /* 7 -- file size   */
  list_mod(CL, 1, "C");          /* 8 -- file name   */
  list_mod(CL, 1, "C");          /* 9 -- ascii/binary transfer */
  list_mod(CL, 1, "C");          /* 10 - special action */
  list_mod(CL, 1, "C");          /* 11 - direction    */
  list_mod(CL, 1, "C");          /* 12 - access mode  */
  list_mod(CL, 1, "C");          /* 13 - user name    */
  list_mod(CL, 1, "C");          /* 14 - service name */
  list_mod(CL, 1, "C");          /* 15 - auth method  */
  list_mod(CL, 1, "C");          /* 16 - auth ID      */


/*  opening the list using the spec */

LL = list_open(CL, 10000000);

/* now process the list */