Parent | Child | Previous | Next
 

onSQLSelectQuery Event

Description

Fires when the Grid needs select records to display in the Grid. If you want to base the Grid on a stored procedure you can use this event to return a resultset to the Grid.

Discussion

Each time the Grid is rendered it executes a SQL query to get a resultset of data to display in the Grid. This event fires before the select query is executed. You can add an event handler to this event to compute the resultset yourself and tell Alpha Anywhere not to try to to get the resultset itself.

If your Grid is based on a stored procedure then you must define code for this event.

If your event handler takes over the responsibility of computing the resultset, it must set these properties:

' Set the resultset to display in the Grid
e.rs = e.cn.resultSet

' Indicate the resultset has been computed and Alpha Anywhere 
' should not query the data source for records
e.handled = .t.

Here is a sample onSQLSelectQuery event handler that you might write:

function onSQLSelectQuery as v (e as p)

    dim flag as L
    flag = e.cn.execute("exec mySelectStoredProcedure @city=:whatcity",e.arguments)
    if flag = .t. then
        e.rs = e.cn.resultSet
        e.handled = .t.
    else
        e.fatalError = .t.
        e.errorText = e.cn.callResult.text
    end if 

end function

In the above example, the resultset that was returned was positioned at the first record. Alpha Anywhere will then navigate in the resultset to the correct starting record to display (for example, you might have requested to show page 3 of the Grid).

However, your stored procedure might be able to 'chunk' the records more efficiently than Alpha Anywhere, and so in addition to the e.handled property you can also set the e.paginationHandled handled property to .t..

The 'e' object that is passed into the onSQLSelectQuery event handler contains the following properties which would be useful if you wanted to handle the pagination of the resultset yourself in the event handler:

  • e.recordCount - number of records in the Grid query
  • e.targetPage - the page number of records to be shown
  • e.targetLogicalRecord - the logical record number of the first record to be shown (e.g. if targetPage is 3 and records per page is 10, then targetLogicalRecord is 21)
  • e.rowCount - the number of records per page to show in the Grid
  • e.pageCount - the number of pages that the Grid contains. (e.g. if the grid contains 25 records and there are 10 records per page, pageCount is 3)

Event Arguments & Properties

The following variables are available to you in the event:

Variable
Description
e.tmpl

The grid component definition

e.rtc

Run-time calculations (allows you to pass data to other event handlers)

e.__si

State information

e.cn

The SQL::Connection object for the Grid. You can call this object's .execute() method to execute your own SQL.

e.sql

The SQL Statement that Alpha Anywhere has computed to get the data to refresh the row.

e.arguments

The SQL::Arguments object with values for all of the arguments in e.sql. To read a value from arguments: e.arguments.find("argumentName").data

e.recordCount

The number of records in the Grid query

e.targetPage

The page number of records to be shown

e.targetLogicalRecord

The logical record number of the first record to be shown (e.g. if targetPage is 3 and records per page is 10, then targetLogicalRecord is 21)

e.rowCount

The number of records per page to show in the Grid

e.pageCount

The number of pages that the Grid contains. (e.g. if the grid contains 25 records and there are 10 records per page, pageCount is 3)

Your event must set the following properties:

Property
Description
e.handled

set to .t. if your event has computed the record count. set to .f. if you want Alpha Anywhere to execute its own count query

e.rs

A SQL::ResultSet of records to show in the Grid (need only be set if e.handled is set to .t.)

e.paginationHandled

The default value for this property is .f., which means that Alpha Anywhere will assume that the first record in the result set that is returned by the event (e.rs) is positioned on the first logical record, and Alpha Anywhere will be responsible for navigating to the correct logical record in the result set. (This property is only meaningful if e.handled is set to .t.)

Your event can optionally set these properties of the e object:

Property
Description
e.fatalError

Set to .t. if a fatal error has occurred

e.errorText

The error text to show if a fatal error occurred

Setting State Variables

You can also set state variables in this event. The value of any state variables will be available in all subsequent ajax callbacks (in the e.__si2 object).

To set a state variable:

e._state.myvar1 = "value1"
e._state.myvar2 = "value2"