CURSORGETPROP( ) Function

  • Article

Retrieves the current property settings for a Visual FoxPro table or a cursor.

Tip

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

CURSORGETPROP(cProperty [, nWorkArea | cTableAlias])

Parameters

  • cProperty
    Specifies the property setting to retrieve.

    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

    ADOBookmark

    Variant

    Contains a value that corresponds to an ADO Bookmark for the current record in an ADO-based cursor.

    ADOCodePage

    N

    Returns the code page bound to an ADO-based cursor as specified by the ADOCodePage Property. Read-only.

    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. The connection handle obtained for a view might close when the view closes.

    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.

    FetchIsComplete

    L

    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

    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.

    MapBinary

    L

    Contains True (.T.) if Varbinary mapping is turned on. Otherwise, contains (.F.).

    Read/write for nWorkArea set to 0 only. Read-only for SQL Pass-Through cursors. Invalid for table cursors (nWorkArea equal to or greater than 1).

    MapVarchar

    L

    Contains True (.T.) if Varchar mapping is turned on. Otherwise, contains False (.F.).

    Read/write for nWorkArea set to 0 only. Read-only for SQL Pass-Through cursors. Invalid for table cursors (nWorkArea 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.

    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.

    RecordsFetched

    N

    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

    Any filter conditions are ignored in the record count.

    Read-only.

    Refresh

    N

    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.

    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 Value

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

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

See Also

Reference

CURSORSETPROP( ) Function
ISMEMOFETCHED( ) Function
SQLGETPROP( ) Function
SQLSETPROP( ) Function

Other Resources

Functions
Language Reference (Visual FoxPro)