Callback Parameter Initialization

In version 7.06.1518116000 20180208 and later, callback parameter initialization is stricter. Any required parameters (those without default values in the function declaration) that are unknown by the specific caller mechanism (SUMFUNC vs. PREVFUNC etc.) cause the callback call to fail with the error "Dynamic function call skipped: Required parameter `...' for function `...' cannot be provided". This alerts the programmer to situations where a callback is expecting a parameter that cannot be provided. In addition, such unknown parameters that do have default values in the function declaration will be passed those default values - and not the same-name-as-parameter global variable value (if set), as start functions do (and callbacks used to, in earlier Texis versions). This is because unlike start functions, callbacks place a definite call with specific arguments, so arguments should only come from that call (or specified default values).

Note that the opposite case - the caller mechanism knows of parameters that are not specified in the callback function - continues to be silently supported. This allows callbacks to not specify parameters they are uninterested in, as well as to make callbacks more forward-compatible with later Texis versions that might add new parameters in caller mechanisms.

DIAGNOSTICS
pagelinks returns 0.

EXAMPLE

<EXPORT $skip URL>
<A NAME=mypg pg curpg>
  <IF $pg eq $curpg>  <!-- on current page already -->
    <B>$pg</B>
  <ELSE>
    <!-- link to other page -->
    <A HREF=$url/search.html>$pg</A>
  </IF>
</A>

<A NAME=search>
  <SQL SKIP=$skip MAX=10 "select Title from books
                          where Subject like $query">
    $next) $Title <P>
  </SQL>
  <!-- custom page links, default prev/next: -->
  <pagelinks PGFUNC=mypg>
</A>

CAVEATS
The pagelinks function is available in version 3.0.943000000 19991119 and later. URLEND, and PGSZ/SKIPVAR defaults, were added in version 3.0.945400000 19991216.

The $skip or SKIPVAR variable must be set to the current page's SKIP value when pagelinks is called. It must also be EXPORTed to the URL or query string in order for links to work, because it is modified for every callback. Any query parameters used in the <SQL> statement should be properly EXPORTed as well.

If the skip variable is local to the function that pagelinks is called from, make sure that all the callbacks declare a parameter with that same name, otherwise the skip will not be EXPORTed since it's out of scope in the callbacks.

Note that URLEND applies only to builtin callbacks, i.e. not to script functions, where the URL is just printed as needed.

While generally consistent, the exact values printed by pagelinks can vary when called at the first row of a SQL loop vs. after the end of the loop. This depends on when $rows.min and $rows.max are known exactly: sometimes not until the last page.

The following Vortex code approximates the behavior of the built-in versions of sumfunc, prevfunc, nextfunc and pgfunc. This code can be used as a starting point for replacing one or more of these functions with custom versions:

<EXPORT $skip $query QUERY>

<A NAME=main>
  <SQL SKIP=$skip MAX=10
      "select ... from mytable where SearchField likep $query">
    <!-- print results -->
  </SQL>
  <$DidTable = "n">
  <$Approx = "y">
  <IF $rows.min eq $rows.max><$Approx = "n"></IF>
  <$SkipOrg = $skip>
  <pagelinks>
</A>

<A NAME=sumfunc numrows startrow endrow pgsz skip>
<LOCAL plural about>
  <IF $DidTable neq "y">
    <TABLE BORDER=0 WIDTH="100%" CELLPADDING=1 CELLSPACING=0
        BGCOLOR="#C0C0C0">
    <$DidTable = "y">
  </IF>
  <TR><TD COLSPAN=3 ALIGN=center><FONT FACE=Helvetica>
  <IF $Approx neq "n"><$about = "about "></IF>
  <IF $numrows neq 1><$plural = "es"></IF>
  <IF $startrow gt $numrows and $Approx eq "n">
    <fmt "Past end of results (%s%kd match%s).\n"
        $about $numrows $plural>
  <ELSE>
    <fmt "%kd through %kd of %s%kd match%s.\n"
      $startrow $endrow $about $numrows $plural>
  </IF>
  </FONT></TD></TR>
</A>

<A NAME=prevfunc numrows startrow pgsz>
  <IF $numrows lte $pgsz and $SkipOrg lte 0><RETURN></IF>
  <IF $DidTable neq "y">
    <TABLE BORDER=0 WIDTH="100%" CELLPADDING=1 CELLSPACING=0
          BGCOLOR="#C0C0C0">
    <$DidTable = "y">
  </IF>
  <TR><TD ALIGN=left VALIGN=center WIDTH="30%">
  <IF $startrow gt 0 or $SkipOrg gt 0>
    <A HREF="$url/$urlfunc$urlext$urlq">
      &lt;&lt;<FONT FACE=Helvetica>previous</FONT></A>
  </IF>
  &nbsp;</TD>
  <TD ALIGN=center WIDTH="30%">
  <IF $numrows gt $pgsz and $numrows gt 0>  <!-- PGFUNC next -->
    Page: <ELSE> &nbsp; </IF>
</A>

<A NAME=pgfunc numrows pg curpg pgsz>
  <IF $numrows lte $pgsz><RETURN></IF>  <!-- 0 or 1 pages -->
  <IF $pg eq $curpg>                <!-- current page "link" -->
    <fmt "<B>%kd</B>\n" $pg>
  <ELSE>
    <A HREF="$url/$urlfunc$urlext$urlq"><fmt "%kd" $pg></A>
  </IF>
</A>

<A NAME=nextfunc numrows pgsz valid>
  <IF $numrows lte $pgsz>           <!-- 0 or 1 total pages -->
    <IF $SkipOrg gt 0>
      </TD>
      <TD ALIGN=right VALIGN=center WIDTH="30%">&nbsp;
      </TD></TR>
    </IF>
    <IF $DidTable neq "y"><RETURN></IF>
    </TABLE>
  </IF>
  </TD>
  <TD ALIGN=right VALIGN=center WIDTH="30%">&nbsp;
  <IF 0 neq $valid>
    <A HREF="$url/$urlfunc$urlext$urlq">
      <FONT FACE=Helvetica>next</FONT>&gt;&gt;</A>
  </IF>
  </TD></TR>
  </TABLE>
</A>

SEE ALSO
SQL and its special variables, especially $rows.min and $rows.max