ADO Recordset Object Move Method

You are here: ADO Component Reference > ADO Objects > ADO Recordset Object > ADO Recordset Object Methods > ADO Recordset Object Move Method

ADO Recordset Object Move Method

Moves the position of the current record in a Recordset object.

Move Method Syntax

recordset.Move NumRecords, Start

Move Method Parameters

NumRecords

A signed Long expression specifying the number of records the current record position moves.

Start

An optional String or Variant that evaluates to a bookmark. You can also use one of the following BookmarkEnum values:


Constant	Description
AdBookmarkCurrent	Default. Start at the current record.
AdBookmarkFirst	Start at the first record.
AdBookmarkLast	Start at the last record.

Move Method Remarks

The Move method is supported on all Recordset objects.

If the NumRecords argument is greater than zero, the current record position moves forward (toward the end of the recordset). If NumRecords is less than zero, the current record position moves backward (toward the beginning of the recordset).

If the Move call would move the current record position to a point before the first record, ADO sets the current record to the position before the first record in the recordset (BOF is True). An attempt to move backward when the ADO Recordset Object BOF, EOF Properties property is already True generates an error.

If the Move call would move the current record position to a point after the last record, ADO sets the current record to the position after the last record in the recordset (EOF is True). An attempt to move forward when the ADO Recordset Object BOF, EOF Properties property is already True generates an error.

Calling the Move method from an empty Recordset object generates an error.

If you pass the Start argument, the move is relative to the record with this bookmark, assuming the Recordset object supports bookmarks. If not specified, the move is relative to the current record.

If you are using the ADO Recordset Object CacheSize Property to locally cache records from the provider, passing a NumRecords that moves the current record position outside of the current group of cached records forces ADO to retrieve a new group of records starting from the destination record. The CacheSize property determines the size of the newly retrieved group, and the destination record is the first record retrieved.

If the Recordset object is forward-only, a user can still pass a NumRecords less than zero as long as the destination is within the current set of cached records. If the Move call would move the current record position to a record before the first cached record, an error will occur. Thus, you can use a record cache that supports full scrolling over a provider that only supports forward scrolling. Because cached records are loaded into memory, you should avoid caching more records than is necessary. Even if a forward-only Recordset object supports backward moves in this way, calling the ADO Recordset Object MoveFirst, MoveLast, MoveNext, MovePrevious Methods method on any forward-only Recordset object still generates an error.

Move Method Example

This VBScript example uses the Move method to position the record pointer based on user input. Try entering a letter or non-integer to see the error-handling work.

<!-- #Include file="ADOVBS.INC" -->

<% Language = VBScript %>

<HTML><HEAD>

<TITLE>ADO 1.5 Move Methods</TITLE></HEAD>

<BODY>

<FONT FACE="MS SANS SERIF" SIZE=2>

<Center>

<H3>ADO Move Methods</H3>

<%

'Create and Open Connection Object

Set OBJdbConnection = Server.CreateObject("ADODB.Connection")

OBJdbConnection.Open "AdvWorks"

'Create and Open Recordset Object

Set RsCustomerList = Server.CreateObject("ADODB.Recordset")

RsCustomerList.ActiveConnection = OBJdbConnection

RsCustomerList.CursorType = adOpenKeyset

RsCustomerList.LockType = adLockOptimistic

RsCustomerList.Source = "Customers"

RsCustomerList.Open

'Check number of user moves this session

'Increment by amount in Form

Session("Clicks") = Session("Clicks") + Request.Form("MoveAmount")

Clicks = Session("Clicks")

'Move to last known recordset position plus amount passed by Form Post method

RsCustomerList.Move CInt(Clicks)

'Error Handling

If RsCustomerList.EOF Then

Session("Clicks") = RsCustomerList.RecordCount

Response.Write "This is the Last Record"

RsCustomerList.MoveLast

Else If RsCustomerList.BOF Then

Session("Clicks") = 1

RsCustomerList.MoveFirst

Response.Write "This is the First Record"

End If

End If

%>

<H3>Current Record Number is <BR>

<% If Session("Clicks") = 0 Then

Session("Clicks") = 1

End If

Response.Write(Session("Clicks") )%> of <%=RsCustomerList.RecordCount%></H3>

<HR>

<Center><TABLE COLSPAN=8 CELLPADDING=5 BORDER=0>

<!-- BEGIN column header row for Customer Table-->

<TR>

<TD ALIGN=CENTER BGCOLOR="#008080">

<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Company Name</FONT>

</TD>

<TD ALIGN=CENTER BGCOLOR="#008080">

<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Contact Name</FONT>

</TD>

<TD ALIGN=CENTER WIDTH=150 BGCOLOR="#008080">

<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>Phone Number</FONT>

</TD>

<TD ALIGN=CENTER BGCOLOR="#008080">

<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>City</FONT>

</TD>

<TD ALIGN=CENTER BGCOLOR="#008080">

<FONT STYLE="ARIAL NARROW" COLOR="#ffffff" SIZE=1>State/Province</FONT>

</TD>

</TR>

<!--Display ADO Data from Customer Table-->

<TR>

<TD BGCOLOR="f7efde" ALIGN=CENTER>

<FONT STYLE="ARIAL NARROW" SIZE=1>

<%= RSCustomerList("CompanyName")%>

</FONT></TD>

<TD BGCOLOR="f7efde" ALIGN=CENTER>

<FONT STYLE="ARIAL NARROW" SIZE=1>

<%= RScustomerList("ContactLastName") & ", " %>

<%= RScustomerList("ContactFirstName") %>

</FONT></TD>

<TD BGCOLOR="f7efde" ALIGN=CENTER>

<FONT STYLE="ARIAL NARROW" SIZE=1>

<%= RScustomerList("PhoneNumber")%>

</FONT></TD>

<TD BGCOLOR="f7efde" ALIGN=CENTER>

<FONT STYLE="ARIAL NARROW" SIZE=1>

<%= RScustomerList("City")%>

</FONT></TD>

<TD BGCOLOR="f7efde" ALIGN=CENTER>

<FONT STYLE="ARIAL NARROW" SIZE=1>

<%= RScustomerList("StateOrProvince")%>

</FONT></TD>

</TR> </Table></FONT>

<HR>

<Input Type = Button Name = cmdDown Value = "< ">

<Input Type = Button Name = cmdUp Value = " >">

<H5>Click Direction Arrows for Previous or Next Record

<BR> Click Move Amount to use Move Method

Enter Number of Records to Move + or - </H5>

<Table>

<Form Method = Post Action="Move.asp" Name=Form>

<TR><TD><Input Type="Button" Name = Move Value="Move Amount "></TD><TD></TD><TD>

<Input Type="Text" Size="4" Name="MoveAmount" Value = 0></TD><TR>

</Form></Table></Center>

</BODY>

<Script Language = "VBScript">

Sub Move_OnClick

' Make sure move value entered is an integer

If IsNumeric(Document.Form.MoveAmount.Value)Then

Document.Form.MoveAmount.Value = CInt(Document.Form.MoveAmount.Value)

Document.Form.Submit

Else

MsgBox "You Must Enter a Number", ,"ADO-ASP Example"

Document.Form.MoveAmount.Value = 0

End If

End Sub

Sub cmdDown_OnClick

Document.Form.MoveAmount.Value = -1

Document.Form.Submit

End Sub

Sub cmdUp_OnClick

Document.Form.MoveAmount.Value = 1

Document.Form.Submit

End Sub

</Script>

</HTML>