function GetRecords(Count: Integer; out RecsOut: Integer; Options: Integer): OleVariant; overload; function GetRecords(Count: Integer; out RecsOut: Integer; Options: Integer; const CommandText: string; var Params, OwnerData: OleVariant): OleVariant; overload;
System::OleVariant __fastcall GetRecords(int Count, /* out */ int &RecsOut, int Options)/* overload */; System::OleVariant __fastcall GetRecords(int Count, /* out */ int &RecsOut, int Options, const System::UnicodeString CommandText, System::OleVariant &Params, System::OleVariant &OwnerData)/* overload */;
Retrieves a data packet that represents the provider's associated data.
Call GetRecords to retrieve a data packet containing a specified number of records. GetRecords generates a BeforeGetRecords event, assembles a data packet, and then generates an AfterGetRecords event.
Count indicates the number of records to retrieve. If Count is -1, all records are retrieved. If Count is 0, only metadata is retrieved. If Count is greater than 0, only the specified number of records are retrieved.
RecsOut returns the actual number of records in the data packet.
Options indicates what information should be added to the data packet in addition to data. It is a combination of the GetRecordOption constants. For example, the following value requests metadata along with a data packet encoded in XML:
MetaDataOption + XMLOption
MetaDataOption || XMLOption
CommandText specifies an optional SQL statement that replaces the SQL of an associated query, or the name of a table or stored procedure that replaces the associated table or stored procedure. This parameter is ignored if the Options property does not include poAllowCommandText or if the provider does not have an Options property.
Params specifies any parameter values that should be applied to CommandText or to an associated query or stored procedure. If the provider is associated with a TTable, Params specifies field values that filter the result set. On exit from GetRecords, Params returns any output parameters.
OwnerData contains custom information that is supplied by a client dataset's BeforeGetRecords event handler. This information is passed to the provider's BeforeGetRecords event handler and is returned by the provider's AfterGetRecords event handler.
Records are returned as a data packet in a Variant.
Note: GetRecords always generates the BeforeGetRecords and AfterGetRecords events, even if you use the syntax that does not include an OwnerData parameter. In that case, the value of OwnerData is nil (Delphi) or NULL (C++) on entry to the BeforeGetRecords event handler and is discarded on exit from the AfterGetRecords event handler.
Tip: If the provider is part of a stateless application server, there is no guarantee that the provider will be positioned on the desired record before it creates a data packet. Use a BeforeGetRecords event handler to position the cursor before the call to GetRecords.