Click or drag to resize

CursorGetProp Function

X#
-- todo --
Retrieves the current property settings for a X# table or a cursor.
Note Note
To set a specific property for a X# table or a cursor, use CursorGetProp( ). For additional information about each of the properties and their settings, see CursorGetProp( ) Function.

Namespace:  XSharp.VFP
Assembly:  XSharp.VFP (in XSharp.VFP.dll) Version: 2.19
Syntax
 FUNCTION CursorGetProp(
	cProperty,
	uArea
) AS USUAL CLIPPER
Request Example View Source

Parameters

cProperty (Optional)
Type: Usual
Specifies the property setting to retrieve. See the table in the remarks section for possible properties.
uArea (Optional)
Type: Usual
Specifies the work area number or the alias of the table or cursor from which the property setting is returned. If you specify 0 for uArea, CursorGetProp( ) returns the environment setting.

Return Value

Type: Usual
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 CursorSetProp( ) is issued without the optional uArea argument. If you use CursorGetProp( ) without a table selected, a cursor open, or an alias specified, you get Error 52 (No table is open in current work area.) unless a work area is specified as in this example, CursorSetProp("Refresh",-2,0).

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.
cPropertyTypeDescription
ADOBookmarkVariantContains a value that corresponds to an ADO Bookmark for the current record in an ADO-based cursor.
ADOCodePageNReturns the code page bound to an ADO-based cursor as specified by the ADOCodePage Property. Read-only.
ADORecordsetO 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.
AllowSimultaneousFetchL 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.
AutoIncErrorL 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.
BatchUpdateCountN 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.
BufferingN 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.
CompareMemoL 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.
ConnectHandleN The connection handle. This property is valid only when the data source contains a remote table. The connection handle obtained for a view might close when the view closes.
Read-only.
ConnectNameC The connection name used when the cursor is created. This property is valid only when the data source contains a remote table.
Read-only.
DatabaseC 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.
FetchAsNeededL 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 Note
FetchAsNeeded does not apply when progressive fetching is disabled (FetchSize is -1).
Read/write.
FetchIsCompleteL If True (.T.), the fetch process is complete for an ODBC or ADO-based cursor.
If False (.F.), the fetch process has not been completed.
This option is not supported for tables and local views or on the environment level (work area 0).
FetchMemo*L Contains True (.T.) if memo fields are fetched with the view results. Otherwise, contains False (.F.). (Default).
Use the ISMEMOFETCHED( ) Function to determine if the memo field has been fetched.
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 Note
Progressive fetching holds the connection until all rows are retrieved. Use caution coding with FetchSize if ShareConnection is True (.T.).
Read/write.
KeyFieldListC A comma delimited list of primary fields for the cursor.
Read/write.
MapBinaryL Contains True (.T.) if Varbinary mapping is turned on. Otherwise, contains (.F.).
Read/write for uArea set to 0 only. Read-only for SQL Pass-Through cursors. Invalid for table cursors (uArea equal to or greater than 1).
MapVarcharL Contains True (.T.) if Varchar mapping is turned on. Otherwise, contains False (.F.).
Read/write for uArea set to 0 only. Read-only for SQL Pass-Through cursors. Invalid for table cursors (uArea equal to or greater than 1).
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.
ParameterListC A semi-colon delimited list of view parameters and parameter types. For views only.
Read/write.
PreparedL 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.
RecordsFetchedN Contains a numeric value that indicates the number of records fetched from the data source for an ODBC or ADO-based cursor.
This numeric value may not reflect the current record count for the cursor if records were locally deleted or appended.
This option is not supported for tables and local views or on the environment level (work area 0).
Note Note
Any filter conditions are ignored in the record count.
Read-only.
RefreshN Contains a numeric value that indicates the refresh setting for an individual cursor in the current data session or an initial refresh value for newly opened cursors in the current data session.
SendUpdatesL 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.
SourceNameN 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.
SQLC The SQL statement executed when the cursor is created.
Read-only.
TablesC A comma delimited list of the names of tables.
Read/write.
UpdatableFieldListC A comma delimited list of fields in the view. This list can include fields from local and remote tables.
Read/write.
UpdateNameListC 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.
UpdateTypeN 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.
WhereTypeN 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.
Examples
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:
X#
1CursorGetProp("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 uArea parameter as the last parameter:
X#
1CursorGetProp("AutoIncError", uArea)
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:
X#
1Close Databases
2Clear
3Open Database (HOME(2) + 'data\testdata')
4Use customer     // Open customer table
5? CursorGetProp("Buffering") // Displays buffering mode
6? CursorGetProp("Database")  // Displays database name
See Also