====== 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|Select...By]] \\ UserArg<2> = Output format when the target is target_variable$ See [[select_into]] |
| //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|Get_Status]].
From TCL the output format options are:
"CSVFILE"
"DHTMLFILE"
"DHTMLPAGE"
"HTMLFILE"
"HTMLPAGE"
"OIPIFILE"
"RTFFILE"
"PDFFILE"
"TXTFILE"
==== See Also ====
[[get_status|Get_Status()]], [[reduce|Reduce]], [[select_by|Select...By]]. Also, [[appendix_a_openlist_keyword_reference|Appendix A: OpenList Keyword Reference]]
==== 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