CursorFill Method

  • Article

Executes the command in the SelectCmd Property property against the data source in the CursorAdapter DataSource property, creates a cursor, retrieves data, and performs any necessary data conversion according to the CursorAdapter DataSourceType Property and CursorSchema Property properties.

CursorAdapter.CursorFill( [ lUseCursorSchema [, lNoData [, nOptions [, Source ] ] ] ] )

Parameters

  • lUseCursorSchema
    The following table lists the values for lUseCursorSchema.

    lUseCursorSchema Description

    True (.T.)

    Uses the schema in the CursorSchema property to create the cursor.

    Note

    Visual FoxPro generates error messages when CursorSchema is required but is missing or invalid.

    False (.F.) or empty

    Does not use the schema in the CursorSchema property to create the cursor.

    Instead, CursorFill creates the cursor using the data types as normally determined by Visual FoxPro according to the CursorAdapter DataSourceType property.

  • lNoData
    The following table lists the values for lNoData.

    lNoData Description

    True (.T.)

    Create the cursor but do not fill it with data.

    When the CursorAdapter DataSourceType property is "ADO", and SelectCmd contains parameters, CursorFill attempts to evaluate the parameters in SelectCmd. If CursorFill cannot evaluate the parameters, it uses null (.NULL.) values for the parameter values.

    When the CursorAdapter DataSourceType property is "XML", CursorFill creates the cursor using the schema in the CursorSchema property, regardless of the value passed to lUseCursorSchema. If CursorSchema is empty or invalid, Visual FoxPro generates an error.

    False (.F.) or empty

    Create the cursor and fill it with data.

    If you specify lNoData for CursorFill, and SelectCmd is a SQL SELECT - SQL Command command against a parameterized view, Visual FoxPro continues to prompt you for parameter input. This action is equivalent to the following statement:

    SELECT * FROM "customers in specific country" WHERE 1=0

  • nOptions
    Specifies numeric values or flags for creating the cursor. The values for nOptions are also used for the CursorRefresh method.

    The following table lists values for nOptions depending on the setting of the CursorAdapter DataSourceType property.

    DataSourceType nOptions

    "ADO"

    An integer representing the Command type or Execution Enum values you want to set for the ActiveX Data Object (ADO) RecordSet Open method. The default value is -1.

    "XML"

    Any combination of valid XMLTOCURSOR( ) Function function flags except 8192, which is automatically set when the lUseCursorSchema parameter contains a value of True (.T.).

  • Source
    Specifies a reference to an ADO Command or an open RecordSet object.

    The ADO Command object must have its ActiveConnection property set to the appropriate and already open ADO Connection object. When an ADO Command object is passed to Source, Visual FoxPro sets the ADO Command CommandText property to value of the CursorAdapter SelectCmd property. Visual FoxPro parses any parameters in SelectCmd, and creates and sets parameter values in the ADO Command object. CursorFill method then executes in the following manner:

    CursorAdapter.DataSource.Open( Source,,,,Options )

    In this call, DataSource is the ADO RecordSet object in the CursorAdapter DataSource property, and Source is the ADO Command object referenced in this parameter.

    The ADO RecordSet object must be open when passed to Source, CursorFill executes against the ADO RecordSet object and populates the cursor accordingly. In this case, only the CursorAdapter DataSourceType property must be set to "ADO". The CursorAdapter SelectCmd and DataSource properties are not used.

    If you do not specify a value for Source, CursorFill executes in the following manner:

    CursorAdapter.DataSource.Open( CursorAdapter.SelectCmd,,,,Options )

    In this call, DataSource is the ADO RecordSet object in the CursorAdapter DataSource property. However, the ADO RecordSet object directly executes the current CursorAdapter SelectCmd property instead of using an ADO Command object. The ADO RecordSet must have its ActiveConnection property set to a valid ADO Connection object.

Return Value

Logical data type. CursorFill returns True (.T.) if the cursor is created successfully and False (.F.) if not created successfully.

Note

If CursorFill returns False (.F.), the cursor is discarded. In this case, the BeforeCursorClose Event and AfterCursorClose Event events do not occur. To retrieve error information when CursorFill returns False (.F.), you must call the AERROR( ) Function function because Visual Foxpro error handling, such as the ON ERROR command, Error event, and TRY...CATCH...FINALLY command, does not capture this error information.

Remarks

Applies To: CursorAdapter Class

The following table lists how CursorFill behaves depending on how the CursorAdapter DataSourceType property is set.

DataSourceType SelectCmd property behavior

"Native"

CursorFill executes SelectCmd, which must contain a SelectCmd a valid Visual FoxPro SQL SELECT command.

"ADO"

CursorFill executes SelectCmd by calling the ADO RecordSet Open method. You must therefore set the CursorAdapter DataSource property to a valid ADO RecordSet object. If SelectCmd contains parameters, you must specify a valid ADO Command object in the Source parameter for the CursorFill method

Manually closing the cursor closes the associated ADO RecordSet. However, this does not apply if the cursor was obtained using the CursorAttach Method method.

CursorFill does not set the ADO RecordSet MaxRecords property to the MaxRecords Property property.

"ODBC"

CursorFill executes SelectCmd using the connection handle of the DataSource property of the CursorAdapter object. Visual FoxPro returns the cursor using SQL Pass-Through. The name of the cursor corresponds to the alias obtained by calling This.Alias.

Note

When several CursorAdapter objects share the same ODBC statement handle, CursorFill might fail for some CursorAdapter objects because another CursorAdapter object has not finished retrieving data. To avoid this situation, set the FetchSize property to 1 for all CursorAdapter objects or use a dedicated ODBC statement handle for each object.

"XML"

One of the following:

  • SelectCmd is an expression that evaluates to a valid XMLTable object. CursorFill calls the XMLTable ToCursor method, and the resulting cursor is attached.

  • SelectCmd is an expression, command, or function that returns XML. CursorFill uses the XMLTOCURSOR( ) function to transform the XML to a cursor. For more information, see the following list of additional remarks.

In addition, when DataSourceType is set to "XML", and SelectCmd is an expression, command, or function that returns XML:

  • The XML requirements are the same as those for the first parameter of the XMLTOCURSOR( ) function. You can specify these requirements by passing the appropriate XMLTOCURSOR( ) nFlags value to the CursorFill nOptions parameter. You can specify additional XMLTOCURSOR( ) flags or combine them as in XMLTOCURSOR( ).

  • CursorFill chooses between eExpression and cXMLFile from XMLTOCURSOR( ) based on nOptions:

    • If nOptions is 0, CursorFill processes XMLSource as eExpression and expects a memory variable containing a valid XML string or an expression that results in an XML string.

    • If nOptions is 512, CursorFill processes XMLSource as cXMLFile and expects a string literal with quotation marks ("") or a memory variable containing a valid file name.

  • The cCursorName parameter in XMLTOCURSOR( ) is always the current value in the Alias property for the CursorAdapter object.

  • If lUseCursorSchema is True (.T.), CursorFill automatically adds the 8192 flag to enforce use of the existing cursor for the XML.

When Visual FoxPro calls CursorFill, it closes the currently attached cursor, if it exists, and the work area that contains the newly created cursor becomes the active work area.

Note

If you wish to preserve the currently attached cursor, call the CursorDetach Method method before calling CursorFill.

When Visual FoxPro attaches a cursor, you cannot change the cursor or table using the MODIFY STRUCTURE Command or SQL ALTER TABLE - SQL Command commands.

See Also

Reference

CursorAdapter Object Properties, Methods, and Events
NoData Property
UseCursorSchema Property
GETCURSORADAPTER( ) Function

Other Resources

Methods (Visual FoxPro)