CanQues 2.0 Protocol/API
Last updated:
January 09, 2007
Questions or comments to: canques@ims.nci.nih.gov
Sample CGI Parameters' in the Report URL
The CanQues site generates an HTML report if the following URL is requested with the right CGI parameters:
http://canques.seer.cancer.gov/cgi-bin/cq_submit?
{Parameters}
An example of {Parameters}
is:
dir=example&db=1&rpt=LINE&sel=0^0^4^0^^2^&x=Age%20at%20diagnosis^1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18&y=Race^0,1,2&dec=1
This will generate a line chart for the example project using database ID 1. Crude rates for female breast cancer will be displayed. The rates presented will be for the time period 1992-1997 and the combination of the eleven standard SEER registries. The X-axis variable will be "Age at diagnosis" with eighteen five-year age groups presented. The series variable will be "Race" with values of "All races", "White", and "Black" presented.
Tetst this link to a real CGI call: Generate the report.
Standard Parameters Detailed Explanations
These parameters are automatically generated and appended in the request URL by the CanQues applet, if used to generate the report. The parameters are generated based on the your working directory's Canques.cfg and *.dic files.
db
ID
property of the "database" section in the (Canques.cfg) project configuration. (E.g., ...&db=1...
)dir
...&dir=example...
)rpt
Report##
properties in the Canques.cfg
configuration file, where ##
is, starting at 1, the consequtive number of the report type. Possible values for report types are: VBAR
, LINE
, TAB
, DATA
. (E.g., ...&rpt=VBAR...
, where the property in the configuration file, for instance, is Report3=VBAR~Vertical Bar Chart
)sel
^
). For instance, ...&sel=1^^^3^4^19^1...
means we will obtain find all records with first field equal to 1
, fourth field equal to 3
, and so forth (where 1
for the first field might correspond to "Both Males and Females", or some other value; consult the *.dic
file specified in the Dictionary
property in the corresponding database section in the Canques.cfg
file)x
, y
, z
...x=Age%20at%20diagnosis^1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18&y=Race^0,1,2...
).^
), and multiple variables per dimension are also separated by carret (^
). Multiple values per variable may be entered, each separated by comma (,
) and each value may be a single value or range (for numeric values, requiring an interval-start integer, hyphen, and an interval-end integer).dec
More Parameters (Not Required)
These parameters are not required and may add extra flexibility or properties to the generated report. ONLY the title
and template
parameters can be set as parameters of the Canques applet (within the <applet>...</applet>
tag); in other words, the template could be forced to call the CanQues reports with these parameters.
title
Name
property of the current project database (in the project Canques.cfg
file). The title text can be overriden, if necessary, by setting the title
parameter value in the CGI call. Use the ~
character in the value to set a line break (<br>
) in the title text when displayed as HTML. (E.g., ...&title=An Example Title~Overrides the default title...
) template
...&template=sometemplate...
)request
parameter is set, the style sheet information specified in the template is overriden, and the custom style sheet will be used. (See the request
and style
parameters' descriptions above.)request
and style
request
value is 1
, the report generated will be HTML that can be saved to disk and previewed offline. Style sheets are embedded and there are no external links pointing out to the Web. Once the report is generated, just go to File > Save As... and save to appropriate location/disc. (E.g., ...&request=1...
) request
is set to 1
, the default style sheet (/CSS/cq_submit.css) will be used. If the style
CGI parameter is set together with request
, it will force the report to embed a different, non-custom style sheet. For instance, if a CGI call is made with ...&request=1&style=small...
, a style sheet named the value of style
plus _cq_submit.css
in the /CSS/
directory will be fetched: in this case, /CSS/small_cq_submit.css
(no error checking is performed to verify the style sheet exists).request
parameter is set, all style information is overriden and the default style sheet (/CSS/cq_submit.css) is used.