CURSORSETPROP( ) Function

  • Article

Specifies property settings for a Visual FoxPro table or a cursor.

CURSORSETPROP(cProperty [, eExpression] [, cTableAlias | nWorkArea])

Return Values

Logical

Parameters

  • cProperty
    Specifies the table or cursor property to set. Note that Buffering is the only property you can specify for a Visual FoxPro table.

  • eExpression
    Specifies the value for the property you specify with cProperty. If you omit eExpression, the property is set to its default value.

    The following table lists the properties you can specify for cProperty and a description of the values eExpression can assume.

    Property eExpression values
    BatchUpdateCount* The number of update statements sent to the remote data source for buffered tables. 1 is the default. Adjusting this value can greatly increase update performance.
    Buffering 1 – Sets row and table buffering off. Record locking and data writing are identical to earlier FoxPro versions. (the default).

    2 – Sets pessimistic row buffering on.

    3 – Sets optimistic row buffering on.

    4 – Sets pessimistic table buffering on.

    5 – Sets optimistic table buffering on.SET MULTILOCKS must be ON for all Buffering modes except 1 (off).
    CompareMemo .T. - Memo fields (of type Memo, General, or Picture) are included in the WHERE clause for updates..F. – Memo fields are not included in the WHERE clause for updates.
    FetchAsNeeded .T. – Records are fetched as needed..F. – For remote views, the number of records fetched is determined by the MaxRecord property. For local views, all records are fetched.
    FetchMemo* .T. – Memo fields are fetched with the view results..F. – Memo fields are not fetched with the view results.
    FetchSize* Number of rows progressively fetched from the remote table result set. The default is 100 rows. Setting FetchSize to –1 retrieves the complete result set (limited by the MaxRecords setting).
    KeyFieldList Comma delimited list of primary fields for the cursor.No default. You must include a list of field names for updates to work.
    MaxRecords* The maximum number of rows fetched when result sets are returned. The default is – 1 (all rows are returned). A value of 0 specifies that the view is executed but no results are fetched.
    Prepared Specify true (.T.) to prepare SQL statements for subsequent REQUERY( ) function calls. REQUERY( ) is used to retrieve data again for a SQL view. See SQLPREPARE( ) for additional information about preparing SQL statements.The default is false (.F.).
    SendUpdates .T. – Specifies that a SQL update query is sent to update tables when an update is made using the view..F. – Specifies that a SQL update query is not sent to update tables.
    Tables Comma delimited list of the names of remote tables.No default. You must include a list of table names for updates to work.
    UpdatableFieldList Comma delimited list of fields in the view. This list can include fields from local and remote tables. You must include a list of fields for updates to work.
    UpdateNameList Comma delimited list of remote field names and the local field names assigned to the cursor. Use this option to specify valid Visual FoxPro names for fields in the cursor that have invalid Visual FoxPro field names.
    UpdateType 1 – Specifies that old data is updated with the new data (the default).

    2 – Specifies that updates occur by deleting the old data and inserting the new data.
    UseMemoSize* Specifies the minimum size (in bytes) for which result columns are returned in memo fields. For example, if the width of a column result is greater than the value of UseMemoSize, the column result is stored in a memo field. UseMemoSize may vary from 1 to 255; the default value is 255.
    WhereType The WHERE clause for updates to remote tables. WhereType may assume the following values:

    1 or DB_KEY (from FOXPRO.H). The WHERE clause used to update remote tables consists of only the primary fields specified with the KeyFieldList property.

    2 or DB_KEYANDUPDATABLE (from FOXPRO.H). The WHERE clause used to update remote tables consists of the primary fields specified with the KeyFieldList property and any updatable fields.

    3 or DB_KEYANDMODIFIED (from FOXPRO.H) (default). The WHERE clause used to update remote tables consists of the primary fields specified with the KeyFieldList property and any other fields that are modified.

    4 or DB_KEYANDTIMESTAMP (from FOXPRO.H). The WHERE clause used to update remote tables consists of the primary fields specified with the KeyFieldList property and a comparison of the time stamps.

    * This property is primarily used for remote views; setting it has no effect on local views. However, you can preset this property for local views that will be upsized.

  • cTableAlias
    Specifies the alias of the table or cursor for which the property is set.

  • nWorkArea
    Specifies the work area of the table or cursor for which the property is set. If you specify 0 for nWorkArea, CURSORSETPROP( ) sets the environment setting used for all subsequent tables or cursors.

    Note   Buffering is not applied to tables that are opened implicitly, for example, using SQL INSERT/UPDATE/DELETE commands.

Remarks

CURSORSETPROP( ) returns true (.T.) if Visual FoxPro successfully sets the property you specify. Visual FoxPro generates an error if the property you specify cannot be set.

The setting of the CURSORSETPROP( ) Buffering property determines how Visual FoxPro performs record locking and update buffering. For additional information on record locking and update buffering, see Buffering Data.

The setting of the CURSORSETPROP( ) WhereType property determines how updates are performed on remote tables. For additional information about remote table updates, see Creating Databases.

You can use CURSORSETPROP( ) to override the FetchSize SQLSETPROP( ) property for a cursor. This property is inherited from the cursor's connection handle by default.

Use CURSORGETPROP( ) to return the current property settings for a Visual FoxPro table or a cursor created for a table.

The property setting is specified for the table or cursor open in the currently selected work area if CURSORSETPROP( ) is issued without the optional cTableAlias or nWorkArea arguments.

Example

The following example demonstrates how you can enable optimistic table buffering with CURSORSETPROP( ). MULTILOCKS is set to ON, a requirement for table buffering. The customer table in the testdata database is opened, and CURSORSETPROP( ) is then used to set the buffering mode to optimistic table buffering (5). A message box is displayed showing the result of the operation.

CLOSE DATABASES
CLEAR

SET MULTILOCKS ON
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer     && Open customer table

* Set buffering mode and store logical result
lSuccess=CURSORSETPROP("Buffering", 5, "customer")
IF lSuccess = .T.
   =MESSAGEBOX("Operation successful!",0,"Operation Status")
ELSE
   =MESSAGEBOX("Operation NOT successful!",0,"Operation Status")
ENDIF

See Also

CURSORGETPROP( ) | SET MULTILOCKS | SQLGETPROP( ) | SQLSETPROP( )