The results of our patent search often take up more than we can comfortably display on one page. Thus we'd like to paginate results across pages, providing previous/next links, and numbering the results.

As we've seen, this can be accomplished with the SKIP and MAX parameters to <SQL> . The special variable $next , at the end of the SQL loop, is set to the amount we need to skip for the next page. Thus, if we <EXPORT nbsp;$next> , we could make a link at the end of the results page to link to the next page. We can also use $next to number individual results inside the SQL loop.

However, we have to do a bit of math to come up with a previous-page link. We also have to do math if we want to provide direct links to every page of results. While simple in principle, it can become tiresome to hand-code the HTML and math to do pagination, every time we write a new search script.

Using <pagelinks>

This is where the <pagelinks> function comes in. Available in Vortex versions after 3.0.945400000 (Dec. 16 1999), it automates the printing of HTML for page links. In our patent example, it's called at the end of the <search> function.

It is normally called right after the ending </SQL> (though it can be called on the first row as well). It prints the "X through Y of Z documents" summary, as well as the page numbers and previous/next links at the bottom. See the Vortex manual on pagelinks for full details on how to configure it. It uses the special variables $rows.min and $rows.max set by <SQL> to compute the page links.

The gory details

In most cases, the total row count is handled automatically by <SQL> and <pagelinks> , as in our patent example. But read on if you want more info on the "behind the scenes" math:

$indexcount

The $indexcount variable is set by <SQL> at the start of the first row returned. It is an estimate of how many total rows the query will returned, based on the index used to help resolve the query.

If the index can completely resolve the query, $indexcount will match the true final result count. We can then use this number to predict how many page links we'll need, and to print the "X through Y of Z documents" summary, as <pagelinks> does automatically.

However, some SQL queries require post-processing or ANDing and cannot be resolved by an index alone. The index matches must be further processed by Texis to determine the final result set. Thus $indexcount is an estimate. The only way to get an exact count in such cases is to let the query run to completion. But that might mean processing thousands of rows, when the user only wants to see the first 10, solely to establish that exactly 98,576 rows matched instead of roughly 100,000. In most cases getting those first 10 matches quickly is more important than knowing the exact count.

$rows.min / $rows.max - A better count

The problem for Vortex programmers is knowing when $indexcount is accurate or not, and to what degree. The $rows.min and $rows.max variables help here. They are the minimum and maximum number of total rows that the query will return. If unknown, they are -1 and -2 respectively. These variables are updated every row, starting with the first, and at the end of the SQL loop. $rows.max is typically the same as $indexcount . $rows.min is often just one ahead of $next , if the exact row count isn't known. (These vars were introduced in Vortex versions after Nov. 16 1999.)

We can use these variables to draw some firmer rules about pagination:

• If $rows.min equals $rows.max , then we have an exact row count. This may occur for completely indexed queries, at the first row and beyond (in a near-future release of Texis). It also occurs at the end of the loop in the obvious case when we exceed MAX .

• If $rows.min is greater than $next at any point, we know there's more rows. <SQL> will do a look-ahead to check for "is there one more row?" and reflect it in $rows.min . This saves us upping MAX by one to check for more rows (ie. next-page).

• If either is greater than or equal to 0, that boundary is known, ie. the minimum or maximum limit.

Of course, we can also just use <pagelinks> and avoid the hassle.