Utilizing the CanQues Hosting Service

Questions or comments to: canques@imsweb.com

In order to make use of the CanQues hosting service, you first need permission from the SEER Program. Carol Kosary (kosaryc@mail.nih.gov) is the point of contact.

With that permission, a username and password will be supplied so you can ftp files to the CanQues server. You'll need to place a single configuration file, and a data file and dictionary per database on the CanQues server.

You'll also be provided with the name of your CanQues hosting service directory which you'll need to generate the necessary HTML on your Web server.

The materials needed to present databases in your own instance of CanQues are discussed below. Examples can be found in the CanQues hosting service directory http://canques.seer.cancer.gov/example/. When you connect to the CanQues server (canques.seer.cancer.gov) with ftp and log on with your username and password, your current working directory will automatically be your CanQues hosting service directory. This is where you place your configuration, data, and dictionary files.

• Canques.cfg - The configuration file is a human readable text file where you enumerate your databases and is the central location where you specify the attributes of each database. It must be named exactly as discussed and the filename is case-sensitive.
  
• example1.bin - For each database, you need a binary data file containing the statistics. The directory data.prep contains the materials used to generate example1.bin. Note that everything done in data.prep is executed on your computer systems and only the resultant binary data file is placed on the CanQues server. The SAS program, example1.sas, generated example1.bin. It reads in the SEER*Stat export file example1.txt.gz which is the output of exporting the results of SEER*Stat session example1.si. See below for more on the binary data files.
  
• example1.dic - For each database, you need a dictionary enumerating the attributes of each identifying variable. Dictionaries are human readable text files.
  
• templates.cfg (optional) - The template configuration file specifies several report layout properties and makes their management easier. A default template for all CanQues projects, templates.cfg, is located at the root of the CanQues hosting site. A custom template configuration file, also named templates.cfg, can be placed in your working directory and can override the default template properties. Multiple report templates may be specified within the same template configuration file and can be used for the same report in different occasions. See the full templates description.
  

Once your content is set up on the CanQues server, you can generate reports either through a Java applet or by creating a URL link to be displayed in a Web browser. The following CanQues 2.0 CGI Protocol/API fully describes the report options and features available in both applet and URL-based invocation. The features allow:

• customizing report layout,
• customizing report body title,
• creating offline reports (code that can be saved and previewed offline),
• showing accessible reports for charts/graphs,
• and more.

If using the CanQues applet, create an HTML page on your Web server referencing the CanQues applet. It will parse the report dictionary (*.dic) and configuration (Canques.cfg) data and provides parameters to generate a request report URL. An example of a CanQues applet used can be found here: Example.html. You'll want to review the source of this page and place the <APPLET >...</APPLET> tag's contents on your Web server. You'll need to change the DirectoryName parameter to your CanQues hosting service directory. The coloring of the applet is handled through six optional parameters.

More on the Binary Data Files

The data files containing statistics are binary with no line terminating characters. Each "record" is fixed length starting with one or more single byte identifying variables and ending with the four byte statistic. The structure of Canques.cfg supports identifying variables of more than one byte and statistics of other than four bytes but neither has been tested. Each identifying variable takes on positive integer values between 0 and 255. The statistic is a signed integer that will be presented with decimal places depending on the StatisticDivisor specified Canques.cfg. The four byte (32-bit) statistic starts with the sign bit at the far left. Moving right, that is followed by the 2³⁰th bit, the 2²⁹th bit, the 2²⁸th bit, and so on down to the 2⁰th bit at the far right.

"Records" of the data file must be sorted ascending by all the identifying variables.

The statistics and data files can be generated with any package or language of your choice and this work is done on your computer systems.