Next / Previous / Contents / TCC Help System / NM Tech homepage

10.1. hist.cgi: Overall flow

Here is the overall flow of the program.

  1. Digest and check the CGI-protocol arguments coming in from the regx.cgi, producing the singleton HistArgs() instance that is referred to everywhere in the program.

    Note that some valid options may result in impossibly absurd reports. For example, suppose the user selects all circles since 1900 and wants split presentation of columns. The validator here is entirely reasonable to reject reports with more than, say, 200 columns.

  2. Open two databases. The CBC database tells us where and when and how many and a six-letter bird code; the xnomo3 XML database places these six-letter codes into the current taxonomy.

  3. Work out the column layout. Taking into account the set of circle centers selected on the form, determine the number of columns. If column splitting is selected, this is the number of effort records for all selected circles. If column lumping is selected, this is the number of unique years in all the effort records for the selected circles.

    An instance of the ColumnLayout base class (either a LumpedLayout or SplitLayout instance) will keep track of which effort keys (year_no+year_key) are routed to which logical columns.

  4. Call the CbcHist constructor. This will search the database for the selected data and organize it into logical rows, one per kind of bird. The CbcHist instance contains one KeyRow instance describing the labels for the columns; one PartyHoursRow instance describing the effort for each column; and zero or more CensusRow instances, one per kind of bird.

  5. Because there are two primary rendering modes (Web page and PDF file), the research phase of the program is next, producing two structures: circleList, a list of the selected Circle instances from the CBC database; and an instance of class lib.CbcHist that contains the bulk of the table.

  6. At the end, control goes to the selected renderer: Section 10.9, “hist.cgi: buildXhtml() or Section 10.22, “hist.cgi: buildPdf(): Render the report as a PDF file”.

    Because the XHTML and PDF table models are fundamentally the same, the logic that allocates logical cells to physical rows is shared between them; see the .fold() method defined in Section 29, “class Row: Abstract class for logical rows”.