You can use the What-If APIs to predict Oracle Clusterware's response to a hypothetical planned or unplanned event. Oracle Clusterware can react to events in the system and produce a response action plan. This action plan consists of a series of resource state transitions or server pool reconfigurations, or both. The What-If APIs provide a mechanism to expose this action plan externally and to enable clients to predict the consequences of an event before it actually happens.
What-If response plans are available for the following event categories:
Oracle Clusterware provides What-If output as a list of actions, where each action represents a specific step performed by Oracle Clusterware. Each action is encapsulated by a clscrs_action structure, and the clscrs_actionlist structure represents the entire sequence of actions. Oracle Clusterware also provides a set of functions (clscrs_action_* for action structures and clscrs_actionlist_* for action lists) to create, examine, iterate over, and destroy these structures. Their usage is identical to that of the corresponding entity list and entity functions.
The What-If APIs also provide clients with the ability to make a query on the projected state of the system. The clscrs_querylist structure using the stat3 format specifies the query, and the clscrs_crsentitylist structure provides the result. Refer to the stat3 section for details on their usage.
Each What-If response that Oracle Clusterware provides includes a sequence ID, which indicates the current state of Oracle Clusterware. The sequence ID is incremented for every new event that Oracle Clusterware manages. Oracle Clusterware guarantees that, as long the sequence ID has not changed, the action plan provided will be executed, as is, for the event in question. For example, the action plan that Oracle Clusterware provides for a whatif start resource FOO request will be identical to the actions Oracle Clusterware takes take when an actual start resource FOO request is submitted, provided the sequence ID has not changed.
Example H-4 describes how you can use What-If APIs.
Example H-4 Sample Usage of What-If API
boolean tracectx = TRUE;
oratext *resid;
clscrs_ctx *ctx;
clscrs_env env;
clscrs_splist *resid_list;
clscrs_action *cur_actn;
clscrs_actionlist *alist;
clscrs_splist *params;
// Init crs
clscrs_init_crs(&ctx, (clscrs_msgf)clsuslztrace, &tracectx, (ub4)0);
// Init parameters to the call
clscrs_entity_id_create(ctx, "MYRES", clscrs_entity_res, &resid);
clscrs_splist_create(ctx, &resid_list);
clscrs_splist_append(resid_list, resid, NULL);
clscrs_actionlist_create(ctx, &alist);
// Make call into the what-if API
clscrs_whatif_start_resource(resid_list, nodename, flags, NULL, NULL, alist);
// Process the resulting list of actions
for(clscrs_actionlist_first(alist,&cur_actn);cur_actn;clscrs_actionlist_next(alist,&cur_actn))
{
params = clscrs_action_getparams(cur_actn);
switch(clscrs_action_gettype(cur_actn))
{
case clscrs_actiontype_resstate:
// Read params and do something
break;
case clscrs_actiontype_srvmove:
// Read params and do something
break;
case clscrs_actiontype_newgroup:
// Read params and do something
break;
case clscrs_actiontype_errorcase:
// Read params and do something
break;
}
}
clscrs_actionlist_destroy(alist);
clscrs_splist_destroy(resid_list);
clscrs_term_crs(&ctx);
Parameters for the APIs listed in this section are separated into those for which you provide input and those that display information when the function completes successfully.