CursorFill Method

  • Article

Executes the command in the SelectCmd property against the data source in the CursorAdapterDataSource property, creates a cursor, retrieves data, and performs any necessary data conversion according to the CursorAdapterDataSourceType and CursorSchema 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 CursorAdapterDataSourceType 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 CursorAdapterDataSourceType 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 CursorAdapterDataSourceType 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 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 CursorAdapterDataSourceType 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 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 CursorAdapterSelectCmd 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 CursorAdapterDataSource 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 CursorAdapterDataSourceType property must be set to "ADO". The CursorAdapterSelectCmd 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 CursorAdapterDataSource property. However, the ADO RecordSet object directly executes the current CursorAdapterSelectCmd property instead of using an ADO Command object. The ADO RecordSet must have its ActiveConnection property set to a valid ADO Connection object.

Return Values

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**and AfterCursorClose**events do not occur. To retrieve error information when CursorFill returns False (.F.), you must call the AERROR( ) function because the ON ERROR command does not execute.

Remarks

The following table lists how CursorFill behaves depending on how the CursorAdapterDataSourceType 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 CursorAdapterDataSource property to a valid ADO RecordSet object. If SelectCmd contains parameters, you must specify a valid ADO Command object in the CursorFillSource parameter.

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

CursorFill does not set the ADO RecordSet MaxRecords property to the CursorAdapterMaxRecords 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.
"XML" One of the following:
  • SelectCmd is an expression that evaluates to a valid XMLTable object. CursorFill calls the XMLTableToCursor 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 CursorFillnOptions 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 before calling CursorFill.

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

See Also

Methods | CursorAdapter Object Properties, Methods, and Events

Applies To: CursorAdapter Class