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:

В	Copy Code
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:

В	Copy Code
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:

В	Copy Code
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.

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.

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