Last modified: October 25, 2012
Applies to: Windows | Windows Server
The JetStopServiceInstance2 function prepares an instance prior to Suspend, and prepares an instance after Resume. Suspend and Resume are execution states of the Windows Store App lifecycle model.
The JetStopServiceInstance2 function was introduced in Windows 8.
JET_ERR JET_API JetStopServiceInstance2( _In_ JET_INSTANCE instance _In_ const JET_GRBIT grbit );
The target instance. The JET_INSTANCE data type is a handle to the instance of the database to use for a call to the JET API. This handle is obtained when you create an instance of the database by calling the JetCreateInstance, JetCreateInstance2, JetInit, or JetInit2 functions.
A group of bits that specifies one or more of the values listed and defined in the following table.
Stops all Extensible Storage Engine (ESE) services for the specified instance.
Stops restartable client-specified background maintenance tasks (B+ Tree Defrag, for example).
Quiesces all dirty caches to disk. This value is asynchronous and can be canceled.
Resumes previously issued StopService operations; that is, it restarts the service. This value can be combined with the grbits parameter to resume specific services, or with JET_bitStopServiceAll to Resume all previously stopped services. This bit can only be used to resume StopServiceBackgroundUserTasks and JET_bitStopServiceQuiesceCaches. If you previously called with JET_bitStopServiceAll, an attempt to use JET_bitStopServiceResume will fail. If the second resume step does not get called, the application will have degraded performance. In this situation the checkpoint is kept at zero.
This function returns the JET_ERR data type with one of the following return codes. For more information about the possible ESE errors, see Extensible Storage Engine Errors and Error Handling Parameters.
The operation completed successfully.
This function allows a JET application to move the database cache to a clean or nearly clean state (with the operating system I/O idle), such that if the application were to be terminated, recovery would be quick. This approach is preferred over terminating JET by calling the JetTerm or JetDetachDatabase functions, so that in the more common scenario, the application is just unsuspended, and later the application has the whole cache and is ready to go as soon as possible.
If this function succeeds, it prepares the database cache for an imminent suspension. This function queues work to a background worker thread and returns to the caller immediately. The function should be called based on the PLM VisibilityNotice as opposed to calling from the application's suspension event handler to ensure that JET has time to flush dirty buffers before PLM suspends/terminates the process. Internally, JET triggers an immediate dispatch of checkpoint maintenance upon configuration change (either checkpoint update or this new quiesce caches bit). For more information about VisibilityNotice events, see VisibilityChangedEventArgs class.
This function must be called twice. It is called after the application receives the suspension notice from the operating system, but before the application has been suspended. Then it is called again after the operating system resumes the application. For example:
When called to Suspend: JET_ERR JET_API JetStopServiceInstance2( instance, JET_bitStopServiceQuiesceCaches);
When Resumed: JET_ERR JET_API JetStopServiceInstance2( instance, JET_bitStopServiceQuiesceCaches|JET_bitStopServiceResume );
Requires Windows 8.
Requires Windows Server 2012.
Declared in Esent.h.