CursorAttach Method

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 CursorAdapterAlias 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 CursorAdapterAlias 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 Values

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

Remarks

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

Methods | CursorAdapter Object Properties, Methods, and Events | Alias Property | ALTER TABLE - SQL Command | MODIFY STRUCTURE Command | CursorDetach Method | BufferModeOverride Property | Updating Remote Data with SQL Pass-Through

Applies To: CursorAdapter Class