CursorSetProp Function |  |
-- todo --
Specifies property settings for a X# table or a cursor.
Namespace: XSharp.VFP
Assembly: XSharp.VFP (in XSharp.VFP.dll) Version: 2.21
SyntaxRequest Example
View Source
Logical data type. CursorSetProp( ) returns True (.T.) if X# successfully sets the property you specify. X# generates an error if the property you specify cannot be set.
Parameters
- cProperty (Optional)
- Type: Usual
Specifies the table or cursor property to set. Buffering is the only property you can specify for a X# table. - eExpression (Optional)
- Type: Usual
Specifies the value for the property you specify with cProperty. If you omit eExpression, the property is set to its default value.
The table in the remarks section lists the properties you can specify for cProperty and a description of the values eExpression can assume. - uArea (Optional)
- Type: Usual
Specifies the alias of the table or cursor for which the property is set or specifies the work area of the table or cursor for which the property is set.
If you specify 0 for uArea, CursorSetProp( ) sets the environment setting used for all subsequent tables or cursors.
Buffering is not applied to tables that are opened implicitly, for example, using SQL Insert/Update/Delete commands.
Return Value
Type: UsualLogical data type. CursorSetProp( ) returns True (.T.) if X# successfully sets the property you specify. X# generates an error if the property you specify cannot be set.
Remarks
The setting of the Buffering property for CursorSetProp( ) determines how X# 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 X# table or a cursor created for a table.
If CursorSetProp( ) is issued without the optional uArea arguments, the property setting is specified for the open table or cursor in the currently selected work area.
* 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.
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 X# table or a cursor created for a table.
If CursorSetProp( ) is issued without the optional uArea arguments, the property setting is specified for the open table or cursor in the currently selected work area.
| 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 multilocs 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.
| ||
| 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.
| ||
| 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. | ||
| 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.
| ||
| 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.
| ||
| 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 uWorkArea parameter to specify a specific cursor. Use uArea = 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.
| ||
| 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. | ||
| UpdateableFieldList | 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. |
NoteExamples
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:
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 uArea parameter as the last parameter:
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.
X#
1CursorSetProp("AutoIncError", .T., 0)
X#
1CursorSetProp("AutoIncError", .F. , uArea )
X#
1Close Databases 2Clear 3Set MultiLocks ON 4Open Database (HOME(2) + 'data\testdata') 5Use Customer // Open Customer table. 6* Set buffering mode and store logical result 7lSuccess=CursorSetProp("Buffering", 5, "Customer") 8IF lSuccess = .T. 9=MessageBox("Operation successful!",0,"Operation Status") 10ELSE 11=MessageBox("Operation NOT successful!",0,"Operation Status") 12ENDIF
See Also