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 */