CICreateCommand

[This is preliminary documentation and subject to change.]

CICreateCommand creates an ICommand object for Index Server, and sets the catalog and machine properties on the object. The ICommand object can be used for issuing queries.

STDAPI CICreateCommand(
  IUnknown ** ppICommand,
  IUnknown * pUnkOuter,
  REFIID riid,
  WCHAR const * pwcsCatalog,
  WCHAR const * pwcsMachine
);
 

Parameters

ppICommand

[out] Address of output variable that receives the interface pointer requested in riid.

pUnkOuter

[in] Points to an optional outer unknown. Can be 0 for no aggregation, in which case riid can be other than IID_IUnknown.

riid

[in] Specifies the IID of the interface returned in ppICommand. Must be IID_IUnknown unless pUnkOuter is 0. Pass IID_ICommand to get an ICommand interface if aggregation isn't needed and pUnkOuter is 0.

pwcsCatalog

[in] Points to a null-terminated string that specifies the name of the catalog used to execute queries. This is the value for the DBPROP_CI_CATALOG_NAME ICommand property.

pwcsMachine

[in] Points to a null-terminated string that specifies the name of the machine on which the query is executed. This is the value for the DBPROP_CI_MACHINE_NAME ICommand property. Specify L"." for the local machine.

Return Values

An HRESULT, S_OK if successful.

Remarks

If interface aggregation isn't required, pass IID_ICommand for riid and 0 for pUnkOuter. Otherwise, call IUnknown::QueryInterface on the returned object to get an ICommand interface.

CICreateCommand does not return an error if the catalog or machine do not exist or are not available. The connection to the catalog and machine are established when ICommand::Execute() is called, and connection errors are returned at that time.

Additional catalog, machine, and scope parameters can be specified after an ICommand is created using the ICommandProperties interface.

Multiple queries can be executed on the ICommand object returned by CICreateCommand, but only one query can exist at a time. Issuing multiple queries on a single ICommand object is much more efficient than creating a new ICommand object for each query.

CICreateCommand is a shortcut for creating OLE DB ICommand objects. It obviates code to create an OLE DB data source object, a session object, an ICommand creation object, then an ICommand object.

Example

This example creates an ICommand object for the system catalog on the local machine.

ICommand * pICommand;
HRESULT hr = CICreateCommand( (IUnknown **) &pICommand, 0, IID_ICommand, L"system", L"." );
if ( SUCCEEDED( hr ) )
{
    // ...
    // execute one or more queries with the ICommand
    // ...
    pICommand->Release();
}