CURSORGETPROP( ) Function
Returns the current property settings for a Visual FoxPro table or a cursor.
To set a specific property for a Visual FoxPro table or a cursor, use CURSORSETPROP( ). For additional information about each of the properties and their settings, see CURSORSETPROP( ).
CURSORGETPROP(cProperty [, nWorkArea | cTableAlias])
Parameters
cProperty
Specifies the property setting to return.The following table includes a list of properties whose settings can be returned, the data type of the return value, and a description of the return value.
cProperty Type Description ADORecordset O Contains an object reference to the ActiveX Data Object (ADO) Recordset associated with the cursor. Not valid for cursors that are not based on ADO Recordsets. Read-only. AllowSimultaneousFetch L Applies when using remote views, a shared connection, and to cursors created using ODBC. AllowSimultaneousFetch contains True (.T.) when similarly configured cursors sharing the connection are permitted to fetch rows simultaneously.
Otherwise, AllowSimultaneousFetch contains False (.F.) when fetching rows simultaneously is not permitted.
AutoIncError L Contains True (.T.) when attempts to insert or update a value in a field that uses automatically incrementing field values generate an error message. Contains False (.F.) when attempts to insert or update a value in a field that uses automatically incrementing field values does not generate an error message and the specified value to be inserted or updated is disregarded.
Applies to cursors and sessions.
Read/write.
BatchUpdateCount* N Contains the number of update statements sent to the remote data source for buffered tables. The default value is 1. Adjusting this value can greatly increase update performance. Read/write.
Buffering N 1 – Row and table buffering is off. (Default) 2 – Pessimistic row buffering is on.
3 – Optimistic row buffering is on.
4 – Pessimistic table buffering is on.
5 – Optimistic table buffering is on.
Read/write.
CompareMemo L Contains True (.T.) if WHERE clause for updates includes memo fields of type Memo, General, or Picture. (Default). Otherwise, contains False (.F.).
For views only.
Read/write.
ConnectHandle N The connection handle. This property is valid only when the data source contains a remote table. Read-only.
ConnectName C The connection name used when the cursor is created. This property is valid only when the data source contains a remote table. Read-only.
Database C The name of the database that contains the table or view. If a table is a free table, Database contains an empty string. Read-only.
FetchAsNeeded L If True (.T.), data is fetched only when needed, such as when record pointer moves to a row that has not been fetched. If False (.F.), additional data is fetched during idle time. (Default)
Note FetchAsNeeded does not apply when progressive fetching is disabled (FetchSize is -1).
Read/write.
FetchMemo* L Contains True (.T.) if memo fields are fetched with the view results. Otherwise, contains False (.F.). (Default). Read/write.
FetchSize* N Contains the number of rows fetched at a time from the remote tables. The default 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.).
Read/write.
KeyFieldList C A comma delimited list of primary fields for the cursor. Read/write.
MaxRecords* N The maximum number of rows fetched when result sets are returned. The default value is – 1 (all rows are returned). A value of 0 specifies that the view is executed but no results are fetched. Read/write.
ParameterList C A semi-colon delimited list of view parameters and parameter types. For views only. Read/write.
Prepared L Contains True (.T.) if SQL statements are prepared for subsequent REQUERY() function calls. Otherwise, contains False (.F.). (Default). REQUERY() is used to retrieve data again for a SQL view. See SQLPREPARE( ) for additional information about preparing SQL statements. For views only.
Read/write.
SendUpdates L Contains true (.T.) if a SQL update query is sent to update tables when an update is made using the view; otherwise, contains false (.F.) (default). Read/write.
SourceName C Contains the long name for a SQL view or a table in a database, or the file path and table name for a free table. Read-only.
SourceType N 1 – The data source is a local SQL view. 101 (1 + 100) - Cursor is created by the CursorFill method.
201 (1 + 200) - Cursor is attached to a CursorAdapter object using the CursorAttach method.
2 – The data source is a remote SQL view.
102 (2 + 100) - Cursor is created by CursorFill.
202 (2 + 200) - Cursor is attached to a CursorAdapter object using CursorAttach.
3 – The data source is a table.
103 (3 + 100) - Cursor is created by CursorFill.
203 (3 + 200) - Cursor is attached to a CursorAdapter object using CursorAttach.
4 - The cursor is based on ADO Recordset and attached to a CursorAdapter object.
104 (4 + 100) - Cursor is created by CursorFill.
204 (4 + 200) - Cursor is attached to a CursorAdapter object using CursorAttach.
Read-only.
SQL C The SQL statement executed when the cursor is created. Read-only.
Tables C A comma delimited list of the names of tables. Read/write.
UpdatableFieldList C A comma delimited list of fields in the view. This list can include fields from local and remote tables. Read/write.
UpdateNameList C 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. Read/write.
UpdateType N 1 – Specifies that old data is updated with the new data. (Default). 2 – Specifies that updates occur by deleting the old data and inserting the new data.
Read/write.
UseMemoSize* N 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 may vary from 1 to 255; the default value is 255. Read/write.
WhereType N The WHERE clause for updates to tables. WhereType can specify the following values: 1 or DB_KEY (from FOXPRO.H). The WHERE clause used to update 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 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 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 tables consists of the primary fields specified with the KeyFieldList property and a comparison of the time stamps.
Read/write.
* The value returned by this property is significant only for remote views; if you get this property for local views, the CURSORGETPROP( ) function returns the default value.
The following table includes a list of properties whose settings can be returned, the data type of the return value, and a description of the return value.
nWorkArea
Specifies the work area of the table or cursor from which the property setting is returned. If you specify 0 for nWorkArea, CURSORGETPROP( ) returns the environment setting.cTableAlias
Specifies the alias of the table or cursor from which the property setting is returned.
Return Values
Character, Numeric, or Logical data type
Remarks
The current property settings are returned for the table or cursor open in the currently selected work area if CURSORGETPROP( ) is issued without the optional cTableAlias or nWorkArea arguments.
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 retrieve the default AutoIncError value for each session by specifying 0 (default session) as the last parameter:
CURSORGETPROP("AutoIncError", 0)
The default session is used when opening a new private data session or cursor. The following example shows how you can retrieve the cursor or table AutoIncError setting for each table by using the nWorkArea or cTableAlias parameter as the last parameter:
CURSORGETPROP("AutoIncError", nWorkArea | cTableAlias)
The following example opens a "Customer" table in the "Testdata" database and uses CURSORGETPROP( ) to display the buffering mode for the table and the name of the database in which the table is contained:
CLOSE DATABASES
CLEAR
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer && Open customer table
? CURSORGETPROP("Buffering") && Displays buffering mode
? CURSORGETPROP("Database") && Displays database name