Record based navigation through the stream. These methods supply features similar to the DB recordsets. The position in the stream is changed to the record specified and the record object is read (filled with the data contained in the stream at the position). Previously contained data in the record is lost (if not explicitly written before the move operation).

Details:

Move - see below

MoveFirst - moves current position to the first record
MoveLast - moves the position over the last existing record (or the beginning of the stream if it is empty)
MoveNext - moves to the next record
MovePrev - moves to the previous record

Syntax:

variable = record_object.Move pos, origin
variable = record_object.MoveNext
variable = record_object.MovePrev
variable = record_object.MoveLast
variable = record_object.MoveFirst

Parameters:

variable - Boolean. Indicates the success of the operation - True means success, False means failure.

pos - Position in the stream - index of the record in the stream where the record object is to be positioned.

origin - How the pos is calculated against:

0 - the beginning of the stream (from the BeginStream byte as set in the fiter)
1 - the current record. E.g. negative pos will move the record backwards and positive will move it forward.
2 - the end of the stream.

Examples:

Example 1:

Set rec = Server.CreateObject("newObjects.utilctls.SFRecord")
Set main = Server.CreateObject("newObjects.utilctls.SFMain")
Set file = main.OpenFile("Somefile.bin")
rec.AddField "FirstName", vbString, 20
rec.AddField "LastName", vbString, 20
rec.BindTo file
rec.MoveFirst
Response.Write rec("FirstName") & " " & rec("LastName")
' Will display the first record from the stream

Example 2:

Set rec = Server.CreateObject("newObjects.utilctls.SFRecord")
Set main = Server.CreateObject("newObjects.utilctls.SFMain")
Set file = main.OpenFile("Somefile.bin")
rec.AddField "FirstName", vbString, 20
rec.AddField "LastName", vbString, 20
rec.BindTo file
rec.Move 0, 2
rec("FirstName") = "John"
rec("LastName") = "Smith"
rec.Update
' Moves the record immediatelly after the end of the stream
' In other words creates new record and sets and writes some data

Example 3:

Set rec = Server.CreateObject("newObjects.utilctls.SFRecord")
Set main = Server.CreateObject("newObjects.utilctls.SFMain")
Set file = main.OpenFile("Somefile.bin")
rec.AddField "FirstName", vbString, 20
rec.AddField "LastName", vbString, 20
rec.BindTo file
rec.MoveFirst
k = 1
While Not rec.EOS
  Response.Write "Record " & k & ": " & rec("FirstName") & " " & rec("LastName") & "<BR>"
  rec.MoveNext
  k = k + 1
Wend
' Lists all the records from the stream.

Remarks:

The behavior of the SFRecord object resembles the behavior of a recordset object (like in ADO or DAO), but there are considerable differences caused by the fact that SFRecord works over streams and not over a data base. There are some actions automatically performed by the recordsets used with data bases, but in case of streams the application is responsible for everything. We designed the SFRecord and SFFilter objects to require as little additional work as possible without losing functionality. Most important are the binding operations (BindTo and ReBind methods) - they allow the filter to inspect the record and determine its representation in the stream.

Move methods change the current position in the stream. If the filter's StreamBegin property is set to a value different than 0 (0 is default) this value takes effect and the stream is treated as like it begins at the byte specified by this property. After moving the record is read from the stream and position is recovered (i.e. the record remains positioned on the same record). To change the contents of the record at the current position in the stream application changes the values of the record's fields and calls the Update method - to update the stream.

When moving the data already contained in the record is not saved (this is the typical behavior of all the similar objects - DB recordsets for example).

One important note for SFRecord. After binding (e.g. call the BindTo or ReBind methods) the record is not positioned, nor read, nor written from/to the stream. Therefore the position of the record in the stream is not guaranteed. To ensure the record is positioned on the first record call MoveFirst (or other method if another position is desired) before doing anything else. However the position is not changed by rebind operations and if before performing the operation the record has been positioned you will need to call only the ReRead method to synchronize the data in the stream and in the record.

Creating new record in the stream is equivalent to moving the current position after the last record. Therefore it can be done by calling record_object.Move 0, 2 and not MoveLast which will move the position over the last existing record.

Applies to: SFRecord object

See also: SFFilter

Supported on:

Windows 95/NT and later
Windows CE 3.0 and later
Pocket PC/Windows Mobile 2003 and later
Windows CE.NET 4 and later