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 -- Must begin with either the keyword SELECT or SQL (case insensitive). list_open() executes the SELECT statement and loads the list with the data returned from the database.
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 three types: ascii (one column), binary (formatted by list_file), 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, or 'X ' for XML.
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");

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 example is an actual working application that uses an FTP logfile, loads it 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, `` ``);
  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 */