CURSORGETPROP(), CURSORSETPROP()

These functions let you inspect and change properties of open tables, views and cursors (the kind you create with CREATE CURSOR and SQL SELECT). The changes you make affect the object (table, view or cursor) only as long as it’s open. For permanent changes, use DBSetProp().

For tables and cursors, the only property that can be changed is Buffering.

Usage

uPropValue = CURSORGETPROP( cProperty [, nWorkArea | cAlias ] )
lSuccess = CURSORSETPROP( cProperty [, uNewValue ]
                         [, nWorkArea | cAlias ] )

The complete property list is in Help, and is reasonably well documented. We’ll go over the errors and omissions here, as well as mention one property that deserves a little light.

Several kinds of “cursors” are affected by these functions: FoxPro tables, both local and remote views, and cursors you create with CREATE CURSOR and SQL SELECT. (The ambiguity of the term “cursor” here is, we suppose, part of the price we pay for having such a flexible language.) Remote views have all the properties listed in Help. Local views have all the properties except ConnectHandle and ConnectName. FoxPro tables and cursors have only four of the listed properties: Buffering, Database, SourceName and SourceType. Checking or changing a property that a particular cursor doesn’t have brings up an error message.

In VFP 6 and earlier versions, the descriptions for UpdatableFieldList and UpdateNameList in Help are backward. UpdatableFieldList contains a comma-delimited list of fields that can be updated in the view. If you use the View Designer, it contains the names of the items with check marks in the "pencil" column. UpdateNameList is sort of like SELECT's AS clause—it matches field names in the result cursor with the source field names. The result field name comes first, followed by a space, followed by the aliased field name in the original source. It, too, is set automatically if you use the View Designer.

Help also says that issuing CURSORSETPROP() without uNewValue resets the property to its default value. Our tests show that to be mostly true, but in each version, some items don’t reset as documented. For example, in every version we tested, FetchMemo resets to .T. when the value is omitted, not to .F. Be sure to either always specify a value or make sure that the property resets to what you think it does before you count on this behavior.

The SourceName property isn’t well-known but is extremely handy for dealing with tables and views with spaces in their names (not something we recommend, of course). The problem is that when you open such a table or view, VFP substitutes spaces for underscores in the alias. If you then try to use some generic code with something like DBGetProp(ALIAS(), …), it’ll bomb because the alias isn’t the same as the name. Instead, use something like:

lcSource = CursorGetProp("SourceName")
DBGetProp(lcSource, ...)

Example

USE Employee
? CURSORGETPROP("Buffering")    && Returns 1
? CURSORGETPROP("SourceName")   && Returns Employee
? CURSORGETPROP("SourceType")   && Returns 3

CREATE DATA Test
CREATE SQL VIEW MyEmps AS ;
    SELECT EmployeeId, First_Name, Last_Name ;
       FROM Employee WHERE Region = ?Region
USE MyEmps
? CURSORGETPROP("Buffering")    && Returns 3
* Set updating properties
* Employee_Id is primary key
? CURSORSETPROP("KeyFieldList", "Employee_Id")
? CURSORSETPROP("UpdateNameList", ;
 "first_name Employee.first_name,last_name Employee.last_name")
? CURSORSETPROP("SendUpdates", .T.)
? CURSORSETPROP("Tables", "Employee")
? CURSORSETPROP("UpdatableFieldList", "First_Name,Last_Name")
* Now the view is updatable

In the second example, we make the view updatable for just this one time. To make it updatable permanently, use DBSetProp() to set the corresponding properties.

See Also

DBGetProp(), DBSetProp(), SQLGetProp(), SQLSetProp()