CURSORSETPROP( ) Function

  • Article

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

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

Parameters

  • cProperty
    Specifies the table or cursor property to set. 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
    AllowSimultaneousFetch Applies when using remote views, a shared connection, and to cursors created using ODBC.

    .T. - Permit similarly configured cursors sharing the connection to fetch rows simultaneously.

    .F. - Do not permit similarly configured cursors sharing the connection to fetch rows simultaneously.
    AutoIncError .T. - Generate an error message when attempting to insert or update values in a field that uses automatically incrementing field values.

    .F. - Does not generate an error message but does not use the value specified when attempting to insert or update the value in a field that uses automatically incrementing field values, which uses the appropriate incremented value.

    Applies to cursors and sessions.
    BatchUpdateCount* Specifies the number of update statements to send to the remote data source for buffered tables. The default value is 1. Adjusting this value can greatly increase update performance when using automatic updating.
    Buffering 1 – Sets row and table buffering off. Record locking and data writing are identical to earlier FoxPro versions. (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. - Include memo fields of type Memo, General, or Picture in the WHERE clause for updates.

    .F. – Do not include memo fields in the WHERE clause for updates.

    Applies when automatic updating is used.
    FetchAsNeeded .T. – Fetch records only when needed, such as when record pointer moves to a row that has not been fetched.

    .F. – Fetch additional data during idle time.

    Note   FetchAsNeeded does not apply when progressive fetching is disabled (FetchSize is -1).
    FetchMemo* .T. – Fetch memo fields with the view results.

    .F. – Do not fetch memo fields with the view results.
    FetchSize* Specifies the number of rows progressively fetched from the remote table result set. The default value is 100 rows. Setting FetchSize to –1 retrieves the complete result set, limited by the MaxRecords setting.
    Note   Progressive fetching holds the connection until all rows are retrieved. Use caution coding with FetchSize if ShareConnection is True (.T.).
    KeyFieldList Specifies a comma-delimited list of primary fields for the cursor. No default. You must include a list of field names for updates to work when using automatic updating.
    MaxRecords* Specifies the maximum number of rows fetched when returning result sets. The default value is – 1, and all rows are returned. A value of 0 specifies that the view is executed but no results are fetched.
    ParameterList Specifies a semi-colon delimited list of view parameters and parameter types. For views only.
    Prepared .T. - Prepare SQL statements for subsequent REQUERY( ) function calls.

    .F. - Do not prepare SQL statements for subsequent REQUERY( ) calls. (Default).

    REQUERY( ) is used to retrieve data again for a SQL view. For additional information about preparing SQL statements, see SQLPREPARE( ) Function.
    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 Specifies a comma-delimited list of the names of remote tables. No default. You must include a list of table names for updates to work when using automatic updating.
    UpdatableFieldList Specifies a 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 when using automatic updating.
    UpdateNameList Specifies a 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 – Update old data with new data. (Default)

    2 – Update by deleting old data and inserting new data.
    UseMemoSize* Specifies the minimum size in bytes for result columns to return 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 can vary from 1 to 255 bytes. The default value is 255 bytes.
    WhereType The WHERE clause for updates to remote tables. WhereType can 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). 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. (Default)

    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.

Return Values

Logical data type. 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.

Remarks

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

The setting of the WhereType property for CURSORSETPROP( ) 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 property in the SQLSETPROP( ) function 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.

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

Example

When a cursor is opened, the default value for the AutoIncError property is read from the session default value, which is the current default data session setting. The following example shows how you can set the default AutoIncError value for each session by specifying 0 (default session) as the last parameter:

CURSORSETPROP("AutoIncError", .T., 0)

The default session is used when opening a new private data session or cursor. The following example shows how you can set the cursor or table AutoIncError setting for each table by using the cTableAlias or nWorkArea parameter as the last parameter:

CURSORSETPROP("AutoIncError", .F. , cTableAlias | nWorkArea )

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 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( )