RList routine
Description
The processing module for OpenList queries RList takes the OpenList statement. The Report Designer uses RList to access data for queries.
Syntax
RList(statement, target, targetname, userarg, debugflag)
Parameters
The Rlist routine has the following parameters.
| Parameter | Description |
|---|---|
| Statement | TheOpenList statement(s) to process. A select statement, a LIST statement or an @fm delimited list of SELECT statements ending with an optional LIST statement. |
| Target | Where to send the output, for example a savelist or a printer or a file or a variable ( see rlist equates ) |
| TargetName | Depending on the value of target, targetname is the name of the resource or variable which receives the output. |
| UserArg | Userarg<1> = which cursor <0,1,2,…8) to employ. See Select...By UserArg<2> = Output format when the target is target_variable$ See Select_Into function |
| Debugflag | If set, the RList output program is saved to disk as RLIST_OUT record in SYSOBJ and the query is not executed. |
| Target | Integer | Description |
|---|---|---|
| TARGET_PRINTER$ | 0 | Send output to default printer (currently only List). |
| TARGET_CLIENT$ | 1 | Send output directly to the client (currently only List); no header/footer. |
| TARGET_VARIABLE$ | 2 | Puts the result into the variable named in the targetName parameter. Use the UserArg parameter to specify the format |
| TARGET_CALLBACK$ | 3 | Call the specified callback function specified in targetname (currently only List). Callback function receives text typically sent to printer. Header, footer and column header data included. |
| TARGET_SAVELIST$ | 4 | (Select only) Saves list to name specified in targetname and/or to rotating queue of 10 last Select queries not left active or latent. |
| TARGET_ACTIVELIST$ | 5 | Resolve the list but do not save it to a named or default list. When RList returns, the list remains active. This is only useful when RList is called procedurally from another SSP. |
| TARGET_LATENTLIST$ | 6 | Do not resolve the list unless absolutely necessary, and do not save it to a named or default list. When RList returns, the list remains active. This is only useful when RList is called procedurally from another SSP. |
| TARGET_CHECKSYNTAX$ | 7 | Check the syntax of the statement and return status information but no not execute. For use by tools that allow users to enter query specifications. |
| TARGET_CALLBACK_NOFMT$ | 8 | Reserved |
| TARGET_BRWDESIGN$ | 9 | Create a Banded report from the RLIST statement, launch the BRW designer to modify the report |
| TARGET_XLIST$ | 10 | Create a banded report from the list statement and run it immediately |
| TARGET_EDITTABLE$ | 11 | set the list property of an edit table whose CtrlEntId is passed in targetname with the result of the rlist statement |
| TARGET_OSFILE$ | 12 | Write result of the rlist statement to an operating system file. Use the UserArg parameter to specify the format |
| TARGET_OLIST$ | 13 | Execute the rlist statement using OLIST. This is the same as calling RUN_REPORT('', statement) |
Note: To check for an error from RList, use Get_Status. For more information, refer to Get_Status.
From TCL the output format options are:
"CSVFILE" "DHTMLFILE" "DHTMLPAGE" "HTMLFILE" "HTMLPAGE" "OIPIFILE" "RTFFILE" "PDFFILE" "TXTFILE"
See Also
Example
* run a Query to create active select, process the list using readnext
$insert RLIST_EQUATES
declare subroutine Rlist
RList("SELECT SYSPROCS WITH ALL [] '$insert' BY @ID", TARGET_ACTIVELIST$)
eof = 0
loop
readnext id else eof = 1
until eof
* Do your processing
repeat
* run a Query, save the results to SYSLISTS
$insert RLIST_EQUATES
declare subroutine Rlist
listId = "MYSELECT"
RList("SELECT SYSPROCS WITH ALL [] '$insert' BY @ID", TARGET_SAVELIST$, listId)
* run a stack of Queries, with a report at the end $insert RLIST_EQUATES declare subroutine Rlist statements = "" statements<-1> = "SELECT PERSON WITH CITY STARTING 'B'" statements<-1> = "SELECT PERSON WITH DOB FROM '01/01/1963' TO '01/01/2003'" statements<-1> = "SELECT PERSON BY CITY BY LNAME BY FNAME" statements<-1> = "LIST PERSON BREAK-ON CITY LNAME FNAME DOB" RList(statements, TARGET_OLIST$)
* run a Query, return result in a variable named keys $insert RLIST_EQUATES declare subroutine Rlist * Format is passed via userarg<2>. "KEYS" returns @fm delimited keys from a select cmd = "SELECT MYTABLE WITH MYCOLUMN = 'SOMEVALUE' BY MYMVCOLUMN" userArg= "":@fm:"KEYS" keys = "" RList(cmd, TARGET_VARIABLE$, keys, userarg)
* Export CSV data $insert rlist_equates declare subroutine Rlist cmd = 'LIST MYTABLE COL1 COL2 COL3 WITH MYCOLUMN="SOMEVALUE"' exportFile = "c:\temp\myfile.csv" userArg= "":@fm:"CSV" ;* Format is passed via userarg<2> RList(cmd, TARGET_OSFILE$, exportFile , userarg)
* return JSON a calling program $insert rlist_equates declare subroutine Rlist cmd = 'LIST MYTABLE COL1 COL2 COL3 WITH MYCOLUMN="SOMEVALUE"' userArg= "":@fm:"CJSON" ;* Format is passed via userarg<2> result = "" RList(cmd, TARGET_VARIABLE$, result, userarg) return result
* populate an edit table using a list statement $insert rlist_equates declare subroutine Rlist cmd = 'LIST MYTABLE COL1 COL2 COL3 WITH MYCOLUMN="SOMEVALUE"' handle = @Window:'.MY_EDITTABLE' RList(cmd, TARGET_EDITTABLE$, handle)
* Create a banded report from a list statement, launch the banded report designer to work on it. $insert rlist_equates declare subroutine Rlist cmd = 'LIST MYTABLE COL1 COL2 COL3 WITH MYCOLUMN="SOMEVALUE"' cmd := ' COLORTHEME "VERDANA" RList(cmd, TARGET_BRWDESIGN$)
* Create a banded report from a list statement, run it without saving. $insert rlist_equates declare subroutine Rlist cmd = 'LIST MYTABLE COL1 COL2 COL3 WITH MYCOLUMN="SOMEVALUE"' cmd := ' COLORTHEME "VERDANA" RList(cmd, TARGET_XLIST$)
* Create a calculated column to run a subquery
* Use a non-zero cursor to avoid corrupting the current select
Equ target_variable$ To 2
query = "SELECT PERSON WITH LNAME EQ " : Quote({LNAME})
cursor = 2
resultFormat = "KEYS"
userArg = cursor:@fm:resultFormat
ans = ""
Call Rlist(query, target_variable$, ans, userarg)
Convert @fm To @vm In ans
Locate @id In ans Using @vm Setting pos Then
ans = Delete(ans,0,pos,0)
end
@ans = ans