CursorAttach Method

  • Article

Attaches an existing cursor to the current instance of a CursorAdapter object.

CursorAdapter.CursorAttach( [ cAlias [, lInheritCursorProperties ] ] )

Parameters

  • cAlias
    Specifies the alias of the cursor or table to be attached.

    When cAlias is specified, CursorAttach populates the CursorAdapter Alias property with the alias of the attached cursor or table. When cAlias is not specified, CursorAttach attempts to attach the cursor or table, which must exist, specified by the current value of the CursorAdapter Alias property.

  • lInheritCursorProperties
    Specifies whether you wish to keep or discard the properties of the cursor or table being attached. The following table lists the possible values for lInheritCursorProperties.

    lInheritCursorProperties Description

    True (.T.)

    Existing properties set for the cursor are inherited by the corresponding properties of the CursorAdapter object.

    False (.F.) or empty

    Existing properties set for the cursor are not copied into the corresponding properties of the CursorAdapter object.

    This option adds flexibility when you are attaching a SQL Pass-Through, Remote View, or other cursor.

Return Value

Logical data type. CursorAttach returns True (.T.) if the cursor is attached successfully and False (.F.) if attachment fails.

Note

To retrieve error information when CursorAttach returns False (.F.), you must call the AERROR( ) Function function because Visual Foxpro error handling, such as the ON ERROR command, Error event, and TRY...CATCH...FINALLY command, does not capture this error information.

Remarks

Applies To: CursorAdapter Class

A cursor or table can have only one instance of a CursorAdapter object attached to it at any given time.

When Visual FoxPro attaches a cursor, you cannot change the cursor or table using the MODIFY STRUCTURE or SQL ALTER TABLE commands.

Calling CursorAttach closes the currently attached cursor. To preserve the currently attached cursor, call CursorDetach first.

Calling CursorAttach populates the Alias property of the CursorAdapter instance with the alias of the attached cursor or table.

Calling CursorAttach turns on BufferModeOverride (3) or BufferModeOverride (5), depending on the BufferModeOverride property for the CursorAdapter object, if not already set. If buffering is already turned on but is less granular than Optimistic Row Buffering, Visual FoxPro promotes buffering to Optimistic Row Buffering.

Visual FoxPro generates error messages under the following conditions:

  • If cAlias cannot be found.

  • If CursorAttach attempts to attach a cursor that is already attached to another instance of CursorAdapter.

The Tables property should not refer to a cursor that was attached to a CursorAdapter object by CursorAttach.

See Also

Reference

CursorAdapter Object Properties, Methods, and Events
Alias Property
ALTER TABLE - SQL Command
BeforeCursorAttach Event
AfterCursorAttach Event
MODIFY STRUCTURE Command
CursorDetach Method
BufferModeOverride Property
GETCURSORADAPTER( ) Function

Concepts

Updating Remote Data with SQL Pass-Through

Other Resources

Methods (Visual FoxPro)