NSPrepareRuleFiring (Transact-SQL)
Prepares the application database for a rule firing. This preparation ensures that a quantum has been scheduled, event views and scheduled subscription views are properly materialized for the quantum, and rule firings are scheduled for the quantum based on the set of events and subscriptions available.
After the stored procedure completes, the application database has a state equivalent to the state that existed prior to rule execution during normal generator operation.
Syntax
[ application_schema_name . ] NSPrepareRuleFiring
[ [ @ReportPossibleEventChronicleUsage = ] chronical_usage_flag ]
[, [ @DisableQuantumLimits = ] quantum_limits_flag ]
Arguments
- [ @ReportPossibleEventChronicleUsage = ] chronical_usage_flag
Indicates whether the prepared rule firing procedure returns a list of possible event chronicles affected or used by the rule firing. A nonzero value causes the routine to return a result set listing the set of event chronicles associated with the prepared rule firing. chronical_usage_flag is tinyint and has a default value of 1.
- [ @DisableQuantumLimits = ] quantum_limits_flag
Indicates whether the scheduling of a new quantum uses the ChronicleQuantumLimit value and SubscriptionQuantumLimit value from the application execution settings in the application definition file (ADF). A nonzero value indicates that the stored procedure should not use these settings to skip one or more quantum periods. quantum_limits_flag is tinyint and has a default value of 1.
Return Code Values
0 (success) or 1 (failure)
Result Sets
NSPrepareRuleFiring produces one or two result sets. The first result set contains information about the rule.
| Column Name | Data Type | Description |
|---|---|---|
QuantumId |
int |
ID number of the quantum for the rule firing. |
QuantumStartTime |
datetime |
Start date and time, in UTC (Coordinated Universal Time or Greenwich Mean Time), of the quantum that contains the rule. |
QuantumEndTime |
datetime |
End date and time, in UTC, of the quantum that contains the rule. |
RuleName |
nvarchar(255) |
Name assigned to the rule in the application definition file (ADF). If no rule is ready to run, this value is NULL. |
EventClassName |
nvarchar(255) |
For event-triggered rules, the name of the related event class. If the rule is a scheduled subscription rule or if no rule is ready to run, this value is NULL. |
SubscriptionClassName |
nvarchar(255) |
Name of the related subscription class. If the rule is an event chronicle rule or if no rule is ready to run, the value is NULL. |
RuleFiringId |
int |
ID number that identifies the prepared rule firing. The column is NULL if no rule firing is ready to run. |
EventBatchId |
bigint |
ID number that identifies the related event batch. If the rule is not an event chronicle or event subscription rule, the application is not processing events in order or there is no rule ready to run, the value is NULL. |
StartScanTime |
datetime |
Start date and time, in UTC, for a prepared scheduled subscription rule. The start date and time must fall between QuantumStartTime and QuantumEndTime. If the rule is not an event chronicle or event subscription rule, the application is not processing events in order, or there is no rule ready to run, the value is NULL. |
EndScanTime |
datetime |
End date and time, in UTC, for a prepared scheduled subscription rule. The end date and time must fall between QuantumStartTime and QuantumEndTime. If the rule is not an event chronicle or event subscription rule, the application is not processing events in order, or there is no rule ready to run, the value is NULL. |
RemainingQuantumRuleFirings |
int |
Number of remaining rule firings to complete rule firing for the quantum. This number count includes any prepared rule firings because they have not run. If there are no rules to prepare, this value is 0. |
The second result set appears only if there are possible effects on the chronicles. The result set is ordered by PossibleChronicleReferenceByRule.
| Column Name | Data Type | Description |
|---|---|---|
PossibleChronicleReferenceByRule |
nvarchar(255) |
Name of the event chronicle that is associated with a prepared rule firing. |
Remarks
Notification Services creates the NSPrepareRuleFiring stored procedure in the application database when you create the instance. When you update the application, Notification Services recompiles the stored procedure.
This stored procedure is in the application's schema, which is specified by the SchemaName element of the application definition file (ADF). If no schema name is provided, the default schema is dbo.
This stored procedure can be executed only when the generator is in the disabled or disabled pending state.
The stored procedure can be called repetitively without calling NSExecuteRuleFiring, but the state in the application database will not be altered. The only way to move the application database state beyond a prepared rule firing is to use the NSExecuteRuleFiring stored procedure or to start the instance.
Permissions
Execute permissions default to members of the NSGenerator and NSRunService database roles, the db_owner fixed database role, and the sysadmin fixed server role.
Examples
A. Report Chronicle Usage and Use Quantum Limits
The following example shows how to prepare the database for the execution of scheduled rules from quantum 1, reporting on the possible use of event chronicles. The rule firing does not ignore quantum limits specified in the ADF.
The application uses the default SchemaName settings, which places all application objects in the dbo schema.
EXEC dbo.NSSetQuantumClock
@QuantumId = 1;
EXEC dbo.NSPrepareRuleFiring
@ReportPossibleEventChronicleUsage = 1,
@DisableQuantumLimits = 0;
B. Use Default Settings
The following example shows how to prepare the database for the execution of scheduled rules from quantum 100, using the stored procedure defaults. The stored procedure does not report event chronicle use and ignores quantum limits.
In this example, the stored procedure (like all other application objects) is in the Stock schema, as specified in the SchemaName element of the ADF.
EXEC dbo.NSSetQuantumClock
@QuantumId = 100;
EXEC Stock.NSPrepareRuleFiring;
See Also
Reference
NSExecuteRuleFiring (Transact-SQL)
NSSetQuantumClock (Transact-SQL)
NSSetQuantumClockDate (Transact-SQL)
Notification Services Stored Procedures (Transact-SQL)
NSExecuteRuleFiring (Transact-SQL)
Other Resources
Notification Services Performance Reports
SchemaName Element (ADF)