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.

    MapBinary

    .T. - At the session level, SQL Pass-Through maps SQL_BINARY, SQL_VARBINARY, and SQL_LONGVARBINARY ODBC types to Varbinary or Blob data type.

    For remote views, the CREATE SQL VIEW command maps the SQL_LONGVARBINARY ODBC data source type to Blob type, and it maps SQL_BINARY and SQL_VARBINARY ODBC data source types to Varbinary type when the precision of the corresponding column in the data source is less than or equal to 254 bytes. When precision is greater than 254 bytes, these types map to Blob type.

    .F. - SQL Pass-Through maps SQL_BINARY and SQL_VARBINARY ODBC types to Character type. (Default)

    For remote views, the CREATE SQL VIEW command maps SQL_BINARY and SQL_VARBINARY ODBC data source types to Memo type.

    Note

    MapBinary is read/write for nWorkArea set to 0, read-only for SQL Pass-Through cursors, and invalid for table cursors (nWorkArea equal to or greater than 1).

    MapVarchar

    .T. - At the session level, SQL Pass-Through maps SQL_WVARCHAR and SQL_VARCHAR ODBC types to Varchar type.

    For remote views, CREATE SQL VIEW command maps SQL_WVARCHAR and SQL_VARCHAR ODBC data source types to Varchar type.

    .F. - SQL Pass-Through maps SQL_WVARCHAR and SQL_VARCHAR ODBC types to Character type. (Default)

    For remote views, CREATE SQL VIEW command maps SQL_WVARCHAR and SQL_VARCHAR ODBC data source types to Character type.

    Note

    MapVarchar is read/write for nWorkArea set to 0, read-only for SQL Pass-Through cursors, and invalid for table cursors (nWorkArea equal to or greater than 1).

    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.

    Refresh

    Specifies a numeric refresh value for an individual cursor in the current data session or an initial refresh value for newly opened cursors in the current data session.

    Use the SET DATASESSION Command to select a specific data session, and use the cTableAlias or nWorkArea parameter to specify a specific cursor. Use nWorkArea = 0 to change the initial refresh value for all newly opened cursors. Any cursors that are already open will not be affected by the new refresh setting.

    SET REFRESH Command allows you to specify a global refresh value. By default, the CURSORSETPROP( ) Refresh setting is -2, which indicates that the current global SET REFRESH value is used. The global SET REFRESH value is specified with its second parameter, nSeconds2.

    You can set the CURSORSETPROP( ) Refresh setting to the same values as the nSeconds2 parameter in SET REFRESH.

    Note   The CURSORSETPROP( ) Refresh setting will be ignored if the nSeconds2 parameter is currently set to zero in the SET REFRESH command.

    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 Value

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 How to: Buffer 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 Developing 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

Reference

CURSORGETPROP( ) Function
SET MULTILOCKS Command
SET REFRESH Command
SQLGETPROP( ) Function
SQLSETPROP( ) Function

Other Resources

Functions
Language Reference (Visual FoxPro)