[Small SEER Logo] [CanQues Title]

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
The project database ID that contains information about the set of data used to generate the report from. The ID value must match the ID property of the "database" section in the (Canques.cfg) project configuration. (E.g., ...&db=1...)
dir
The project directory, starting at the CanQues hosting site. Determines where the CanQues program will look for the configuration information and data sets. (E.g., ...&dir=example...)
rpt
The report type requested. The report types allowed for the current database are specified in the 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
The field(s) (by which we search for records) that have a fixed value -- aka "selected fields". The values are delimited by a carret (^). 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
The fields (by which we search for records) that more than one value - aka "variables". Therefore, all records that have either value from the ones specified in x, y, and z, will be retrieved. To display the records' in legible form, the "variables" values are laid along either the x-axis, y-axis, or z-axis. The z-axis is a third dimension used for the "Table" or "Data Delimited" reports, creating a separate table for each value of the z-axis field. For "Vertical Bar Graph" or "Line Chart" types the y-axis is displayed as a separate bar value or separate series value, respectively, for each x-axis value. (E.g., ...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...).

Multiple values per variable in x, y, or z dimensions can be entered. For each dimension, a pair of variable name and variable value(s) is separated by a carret (^), 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
The decimal places to be shown in the statistics' results numbers.

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
The visible body title, by default, comes from the 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
Sets the template to be used when generating the report by specifying a template ID. (E.g., ...&template=sometemplate...)

Note: if the 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.)

For more information see the templates documentation page.
request and style
If 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...)

If 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).

Note: when the request parameter is set, all style information is overriden and the default style sheet (/CSS/cq_submit.css) is used.