Data Access Library for Eiffel contents structure

RECORDSET

DALE offers the special container class to deal with records as results of a query.

The RECORDSET class is the container of RECORDs.

In contrast of universal containers, the RECORDSET has only one source for its items - results from a query. Therefore, every RECORDSET should be associated with a query before use.

As it was mentioned above, a query can be attached to a database or unattached. Being attached a query can be active or not active at the moment. The query's state is defined by the method it was created. Taking the last into account, the RECORDSET class has different features to be associated with a query being in different states:

In the description of the SIMPLE_QUERY class it was referred to the recordset feature as a way to obtain a recordset from a query. This feature is in symmetry with the RECORDSET's build.

Note, that the query become attached anyway. However, it is not necessary for the query to be active at once.

By default, the recordset is static. It means that it represents a two-way scrollable list with random access to records by the ordinal position and it is implied in the examples below. Look the QUERY_OPTIONS class to find out how to change query's settings.

The feature cursor is inherited from the TRAVERSABLE class and carries out almost the same as in usual containers - delivers new recordset's cursor, i.e. an object of the RS_CURSOR class, which can then be used to traverse. However, there is one difference: if this feature is called at first time and the associated query is not active, it will be executed automatically. See the RS_CURSOR class for more information.

Another important feature is item_at which accepts the cursor positioned at some record and returns that record.

As a rule, you pick the record to gain an access to its fields. The RECORDSET class contains two special features: field and field_no. Both of them accept the recordset's cursor as the first argument. Second argument is a STRING for field and an INTEGER for field_no denoting field's symbolic name and the ordinal position respectively. See also the RECORD and FIELD class for more information.

To refresh the contents of the recordset you can use the refresh feature. Remember, that all active cursors will be automatically stopped.

Often you need to read the contents of small-sized table at once. To simplify your task and speed up the performance it is possible to use the to_array feature which delivers an array of loaded records.

When there is no need in a recordset anymore you have to close it with the help of the close feature. All active records will be close automatically. What will happen with the associated query depends on the way was chosen to obtain recordset. If recordset was created via the open feature which creates a query anew, that query will be closed together with recordset. Otherwise, the query will not be closed, but if it was not active before creating of the recordset, it will be made inactive.

i  : INTEGER
db : DATABASE
sel: SQL_SELECT
rs : RECORDSET
c  : RS_CURSOR
r  : RECORD
s  : STRING

-- Query: select all the people living in Moscow:
!!sel.select_ ("Person_Name, Age, Address, Phone",
	"People, Cities",
	"People.City_ID = Cities.City_ID and City_Name = 'Moscow'")

!!rs.open (db, sel)  -- open recordset with results

-- output records one-by-one:
from
	c := rs.cursor  -- open cursor (implies execution of the query)
until
	c.is_finished
loop
	-- print all fields of record:
	from
		i := 1
		r := rs.item_at (c) -- get record under the cursor
	until
		i > r.count  -- for all fields in the record
	loop
		io.put_string (r.field_no (i).name)  -- output field name
		io.put_string (": ")    -- pad between field name and value

		if r.field_no (i).is_null then
			io.put_string ("(null)")
		else
			-- output field value:
			io.put_string (r.field_no (i).to_string)
		end -- if

		io.put_newline
		i := i + 1
	end -- loop

	c.forth
end -- loop

rs.close -- stop all open cursors and close recordset

Copyright © Object Tools -- info@object-tools.com
Last updated: 2005/02/02 11:51:24