H Oracle Clusterware C Application Program Interfaces

Overview

CLSCRS is a set of C-based APIs for Oracle Clusterware. The CLSCRS APIs enable you to manage the operation of entities that are managed by Oracle Clusterware. These entities include resources, resource types, servers, and server pools. You use the APIs to register user applications with Oracle Clusterware so that the clusterware can manage them and maintain high availability. Once an application is registered, you can manage it and query the application's status. If you no longer need the application, then you can stop it and unregister it from Oracle Clusterware.

Oracle Clusterware services are provided by Cluster Ready Services that runs as part of Oracle Clusterware. The CLSCRS API uses a context that is explicitly named in all function calls. The API does not store anything at the process or thread level. You can use the callbacks for diagnostic logging.

Operational Notes

This section includes the following topics:

• Context Initialization and Persistence

• Threading Support

• CLSCRS API Data Structures

• Memory Management

• Error Handling and Tracing

• Callback Mechanism

• Filters

• Script Agent Usage

• Help Interface

Context Initialization and Persistence

To use the CLSCRS APIs, you must first initialize the clscrs context. The calls to create and terminate this context are:

• clscrs_init_crs: Initializes the clscrs context

• clscrs_term_crs: Terminates the clscrs context

The caller is responsible for terminating the context when it is no longer needed.

Threading Support

If initialized with the CLSCRS_FLAG_USETHREADS flag, then the CLSCRS API may spawn threads internally. Every API function executes in the context of the calling thread. The API context object may not be used concurrently by multiple threads. However, no thread-affinity on the part of the client is required. A process may create multiple API contexts and use those on different threads, subject to the one-thread-per-one-context-at-a-time rule.

CLSCRS API Data Structures

The following entities are passed into the API calls and contain return values from the API call:

• clscrs_sp: A stringpair (sp) contains a name and a value string. The value can be NULL. It is created and destroyed, and its contents can be examined and the value replaced. A stringpair can be a member of exactly one stringpair list (splist).

• clscrs_splist: A stringpair list (splist) is a list of zero or more stringpairs used in various contexts. An API can add stringpairs to or remove them from a stringpair list, or the API can iterate stringpairs.

• clscrs_entity_type: The enumeration type you can use to identify the type of Oracle Clusterware entity.

  The enumeration types are defined, as follows:

  /* enum to specify the entity type */ 
  typedef enum
  { 
     clscrs_entity_res              = 1, /* resource */ 
     clscrs_entity_restype          = 2, /* resource type */ 
     clscrs_entity_serverpool       = 3, /* server pool */ 
     clscrs_entity_server           = 4, /* server */ 
     clscrs_entity_resinst          = 5, /* resource instances */ 
     clscrs_entity_config_policy    = 6, /* configuration policy */ 
     clscrs_entity_config_policyset = 7, /* configuration policy 
  set */ 
     clscrs_entity_server_category  = 8  /* server category */ 
  } clscrs_entity_type;
  

• clscrs_crsentity: This data structure (crsentity) represents an Oracle Clusterware entity, which contains the name and additional data appropriate to the context in which the Oracle Clusterware entity is used. Sometimes an API contains Oracle Clusterware entity attribute data and other times it carries status and return messages about an operation. A single entity can be a member of exactly one clscrs_crsentitylist.

• clscrs_crsentitylist: An entity list (crsentitylist) is a data structure that contains zero or more instances of a clscrs_crsentity. An API can add entities to or remove them from an entity list, or the API can iterate entities.

Memory Management

The CLSCRS APIs work on elements and lists. The elements are added to lists. The memory for both elements and lists is allocated and released through explicit API calls. It is the caller's responsibility to release the memory that they allocate. However, when elements are added to lists, only the list must be destroyed: the destruction of the list destroys its elements implicitly. The elements must be destroyed when they are not added to any list. For recursive lists, destroying the parent list also destroys any lists contained within it. The clscrs_sp and clscrs_crsentity elements must be destroyed by the caller. If they are part of a clscrs_splist or clscrs_crsentitylist, destroying the list destroys the respective clscrs_sp and clscrs_crsentity entities.

For example, when a resource is created and added to a resource list, only the resource list must be destroyed, but not the individual resource. Destroying the resource list releases the memory for the individual resource, too.

Memory is allocated by the API through the following calls:

clscrs_sp_create()
clscrs_crsentity_create()
clscrs_serverpool_create()
clscrs_type_create()
clscrs_splist_create()
clscrs_crsentitylist_create()
clscrs_entity_id_create()

Each of the calls in the preceding list has a corresponding clscrs_*_destroy() call.

Error Handling and Tracing

Interactive and non-interactive CLSCRS APIs each use a different error-handling mechanism.

For non-interactive CLSCRS APIs, the error code is returned as the return value of the function call. For example:

clscrsret clscrs_sp_get_value(clscrs_sp *sp, oratext **value);

The error code is returned as a clscrsret value.

For interactive CLSCRS APIs, the output result is represented, as follows:

1. The return value of the function call provides a high-level output of the request. Did the request reach the server? Was it completely successful, or completely or only partially unsuccessful? A successful return value means the request was received, processed, and the outcome was successful for all entities requested.

2. For each entity on which the request operated, there is a programmatic completion code stored in the op_status list. If the value is not success, it indicates the high-level type of the problem specific to processing the request for the particular object.

3. Optionally, the API might indicate that it wants to receive localized, human-readable error, warning, or status messages by using the callback mechanism. Each invocation of the callback provides the message, message type (severity), and the ID of the object to which the callback invocation pertains.

For example:

CLSCRS_STAT clscrs_register_resource2(clscrs_crsentitylist *in_crsentitylist, uword flags,
                                       clscrs_msgf2 msgf, void *msgarg,
                                       clscrs_crsentitylist *op_status);

1. The function returns an error code of value CLSCRS_STAT.

2. The CRSD sends error messages, warning messages, and progress messages back to the client through the clscrs_msgf2 callback. The client must implement the callback to process these messages returned by the CRSD.

3. In previous Oracle Clusterware releases, the API also contained results of each operation on the Oracle Clusterware entities as part of the op_status list. You can access that information using the following API:

   clscrsret clscrs_entity_get_op_status(clscrs_entity *res, CLSCRS_STAT *status,
                                       oratext **msg);
   

   The status argument contains a status code about the CRSD operation on the Oracle Clusterware entity. Additionally, the msg argument contains a message from the CRSD about the result of the operation. Though the op_status list continues to contain the results of the CRSD operation for each Oracle Clusterware entity in the msg argument, usage of the msg argument to get the error codes and messages has now been deprecated and is not supported for any use of the API on a new entity. Only pre-existing use cases (for acting on resources, specifically) are supported. Use the callback function to process any messages returned by the CRSD.

Callback Mechanism

Interactive CLSCRS APIs provide a callback mechanism that the clients can use to process error messages, warning messages, and progress messages sent by the CRSD.

The signature of the callback mechanism is:

typedef  void (*clscrs_msgf2)(void *usrp, const oratext *id, const oratext *msg,
                clscrs_msgtype msgtype);

In the preceding syntax:

• usrp: Is a user-supplied pointer that probably contains the context of the call

• id: Is the identifier of the entity to which the message corresponds

• msg: Is the output text

• msgtype: Is the type of the message; either error, warning, or progress

Example H-1 describes an example of the callback mechanism.

void myCallback(void *arg, const oratext *pId, const oratext *pMsg,
                clscrs_msgtype msgType)
{
    if (pMsg != NULL)
   {
       cout << pMsg << endl;
    }
}

Example H-2 describes how to use the callback mechanism in an interactive API.

clscrs_start_resource2(pResIdList, NULL,
                       env, myCallback, NULL,
                       0, pOpStatus);

You can also print debug trace messages for the API, itself by passing the CLSCRS_FLAG_TRACE flag when creating the context. The signature for context creation is:

CLSCRS_STAT clscrs_init_crs(clscrs_ctx **ctx, clscrs_msgf2 errf, void *errCtx,
                             ub4 flags);

For the trace messages to work, you must specify both the CLSCRS_FLAG_TRACE flag and a clscrs_msgf2 callback mechanism in the clscrs_init_crs API.

The clscrs_msgf2 callback mechanism has the following signature:

typedef  void (*clscrs_msgf)(void *usrp, const oratext *msg, sword msglen);

Filters

You can use filters to narrow down Oracle Clusterware entities upon which a CLSCRS API operates. Simple filters are attribute-value pairs with an operator. Operators must be surrounded by spaces, as shown in the examples. You can combine simple filters into expressions called expression filters using Boolean operators.

Supported filter operators are:

Supported Boolean operators are AND and OR.

Examples of filters are:

• TYPE = type1

• ((TYPE = type1) AND (CHECK_INTERVAL > 50))

• (TYPE = type1) AND ((CHECK_INTERVAL > 30) OR (AUTO_START co never))

• NAME en network.res

• TYPE st ora.db

There are two types of filters and CLSCRS has a set of APIs to create these filters:

• Comparison filter: A simple filter that compares two values. For example:

  TYPE = ora.db.type
  

  Use the clscrs_compfilter_create API to create a comparison filter. For example, to create the (TYPE = ora.db.type) comparison filter:

  clscrs_compfilter_create(ctx, clscrs_TYPE,
                      clscrs_comparator_eq, (const oratext *)"ora.db.type",
                      &myCompFilter);
  

• Expression filter: A filter that is created from either a set of comparison filters or expression filters, or both. For example:

  ((TYPE = ora.db.type) AND (CHECK_INTERVAL > 50))
  

  Use the clscrs_expfilter_create API to create a comparison filter. For example, to create an expression filter:

  clscrs_exprfilter_create(myCompFilter1, clscrs_operator_or,
                            myCompFilter2, &myExprFilter);
  

You can use filters in the following interactive CLSCRS APIs in place of an entity list:

Example H-3 describes using filters in an interactive CLSCRS API.

clscrs_start_resource2(myCompFilter, NULL,
                       env, msgf2, NULL,
                       0, pOpStatus);

Script Agent Usage

When you use CLSCRS APIs inside script agent entry points, keep the following in mind:

1. Some actions, such as start, stop, and clean, are executed under a lock on the resource instance. Thus, issuing a request to the server to act on the resource directly or by extension of a relation results in a dead-lock.

2. Issuing read-only (clscrs_stat2) is generally safe unless it is an initial check, where the script agent must not call back on the server, because that results in a dead-lock, as well. Use the clsagfw APIs to query the check entry point.

Help Interface

You can find the entire list of CLSCRS APIs, including usage information for each, in the $ORA_CRS_HOME/crs/demo/clscrsx.h file, along with a demo called crsapp.c.

Deprecated CLSCRS APIs

Table H-1 lists the deprecated CLSCRS APIs and the corresponding replacement APIs for Oracle Clusterware.

clscrs_check_resource

clscrs_check_resource2

clscrs_entity

clscrs_entity_type

clscrs_fail_resource

clscrs_msgf

clscrs_msgf2

clscrs_register_resource

clscrs_register_resource2

clscrs_relocate_resource

clscrs_relocate_resource2

clscrs_res_attr_count

clscrs_crsentity_attr_count

clscrs_res_create

clscrs_crsentity_create

clscrs_res_create

clscrs_crsentitylist_create

clscrs_res_destroy

clscrs_crsentity_destroy

clscrs_res_get_attr

clscrs_crsentity_get_attr

clscrs_res_get_attr_list

clscrs_crsentity_get_attr_list

clscrs_res_get_name

clscrs_crsentity_get_name

clscrs_res_get_node_list

clscrs_crsentity_get_node_list

clscrs_res_get_op_status

clscrs_crsentity_get_op_status

clscrs_res_get_reslist

clscrs_crsentity_get_crsentitylist

clscrs_res_set_attr

clscrs_crsentity_set_attr

clscrs_res_set_attr_list

clscrs_crsentity_set_attr_list

clscrs_res_set_reslist

clscrs_crsentity_set_crsentitylist

clscrs_reslist_append

clscrs_crsentitylist_append

clscrs_reslist_count

clscrs_crsentitylist_count

clscrs_reslist_delete_res

clscrs_crsentitylist_delete_crsentity

clscrs_reslist_destroy

clscrs_crsentitylist_destroy

clscrs_reslist_find

clscrs_crsentitylist_find

clscrs_reslist_first

clscrs_crsentitylist_first

clscrs_reslist_next

clscrs_crsentitylist_next

clscrs_start_resource

clscrs_start_resource2

clscrs_stat

clscrs_stat2

clscrs_stop_resource

clscrs_stop_resource2

clscrs_unregister_resource

clscrs_unregister_resource2

Changes to Existing CLSCRS APIs

Oracle has added the following flags to the clscrs_stat2 API:

• CLSCRS_STATFLAG_SERVERBYCATEGORY: Use this flag to query the servers that match a particular server category.

• CLSCRS_STATFLAG_CATEGORYBYSERVER: Use this flag to query the server categories that match a particular server.

Oracle has added the following flags to the clscrs_start_resource2 and clscrs_stop_resource2 APIs:

• CLSCRS_FLAG_T_HA_PREPARE: Use this flag with Transparent HA (start2/stop2 APIs) to instruct the Oracle Clusterware daemon (CRSD) to prepare for an external management interface to act on a resource. When the call comes back, if successful, then the interface then is expected to start or stop the resource and call back with the other flag (CLSCRS_FLAG_T_HA_FINISH).

• CLSCRS_FLAG_T_HA_FINISH: Use this flag with Transparent HA with CLSCRS_FLAG_T_HA_PREPARE. You must use this flag in the second call to the CRSD (start2/stop2 APIs) when the start or stop action has finished. Note that clients must indicate resource instances and never resources with this flag, because the CRSD must know to which instances the invocation of the API applies.

• CLSCRS_NO_STATE_RESTORATION: This flag is available for use to start and stop resource APIs and to instruct the CRSD to skip resource state restoration of the resources whose state was affected. That procedure is usually attempted unless you use this flag.

clscrs_whatif_register_resource

The clscrs_whatif_register_resource API determines the actions that Oracle Clusterware would take if you add or modify a specific resource.

clscrs_whatif_register_resource(const oratext *name, clscrs_splist *attrs,
                                 uword flags, clscrs_querylist *qlist,
                                 clscrs_crsentitylist *status,
                                 clscrs_actionlist *alist);

clscrs_whatif_fail_resource

The clscrs_whatif_fail_resource API determines the actions that Oracle Clusterware would take if specific resources failed.

clscrs_whatif_fail_resource(clscrs_splist *name, const oratext *server,
                             uword flags, clscrs_querylist *qlist,
                             clscrs_crsentitylist *status,
                             clscrs_actionlist *alist);

clscrs_whatif_start_resource

The clscrs_whatif_start_resource API determines the actions that Oracle Clusterware would take if you started specific resources.

clscrs_whatif_start_resource(clscrs_splist *name, const oratext *node,
                              uword flags, clscrs_querylist *qlist,
                              clscrs_crsentitylist *status,
                              clscrs_actionlist *alist);

clscrs_whatif_stop_resource

The clscrs_whatif_stop_resource API determines the actions that Oracle Clusterware would take if you stopped specific resources.

clscrs_whatif_stop_resource(clscrs_splist *name, uword flags,
                              clscrs_querylist *qlist,
                              clscrs_crsentitylist *status,
                              clscrs_actionlist *alist);

clscrs_whatif_relocate_resource

The clscrs_whatif_relocate_resource API determines the actions that Oracle Clusterware would take if you relocated specific resources.

clscrs_whatif_relocate_resource(clscrs_splist *name, const oratext *destnode,
                              uword flags, clscrs_querylist *qlist,
                              clscrs_crsentitylist *status,
                              clscrs_actionlist *alist);

clscrs_whatif_register_serverpool

The clscrs_whatif_register_serverpool API determines the actions that Oracle Clusterware would take if you registered a specific server pool.

clscrs_whatif_register_serverpool(const oratext *pname, clscrs_splist *attrs,
                                   uword flags, clscrs_querylist *qlist,
                                   clscrs_crsentitylist *status,
                                   clscrs_actionlist *alist);

clscrs_whatif_unregister_serverpool

The clscrs_whatif_unregister_serverpool API determines the actions that Oracle Clusterware would take if you unregistered a specific server pool.

clscrs_whatif_unregister_serverpool(const oratext *poolname, uword flags,
                                     clscrs_querylist *qlist,
                                     clscrs_crsentitylist *status,
                                     clscrs_actionlist *alist);

clscrs_whatif_add_server

The clscrs_whatif_add_server API determines the actions that Oracle Clusterware would take if you added a server.

clscrs_whatif_add_server(const oratext *name, clscrs_splist *attrs, uword flags,
                          clscrs_querylist *qlist, clscrs_crsentitylist *status,
                          clscrs_actionlist *alist);

clscrs_whatif_relocate_server

The clscrs_whatif_relocate_server API determines the actions that Oracle Clusterware would take if you relocated a server to a different server pool.

clscrs_whatif_relocate_server(const oratext *name, const oratext *topool,
                               uword flags, clscrs_querylist *qlist,
                               clscrs_crsentitylist *status,
                               clscrs_actionlist *alist);

clscrs_whatif_delete_server

The clscrs_whatif_delete_server API determines the actions that Oracle Clusterware would take if you deleted a server.

clscrs_whatif_delete_server(const oratext *name, uword flags,
                             clscrs_querylist *qlist,
                             clscrs_crsentitylist *status,
                             clscrs_actionlist *alist);

clscrs_whatif_set_activepolicy

The clscrs_whatif_set_activepolicy API determines the actions that Oracle Clusterware would take if you activated a specific policy.

clscrs_whatif_set_activepolicy(const oratext *name, uword flags,
                                clscrs_querylist *qlist,
                                clscrs_crsentitylist *status,
                                clscrs_actionlist *alist);

clscrs_servercategory_create

The clscrs_servercategory_create API creates a server category.

clscrs_servercategory_create(clscrs_ctx *ctx, const oratext *sc_name,
                                clscrs_crsentity **sc);

clscrs_servercategory_destroy

The clscrs_servercategory_destroy API frees memory for a server category.

clscrs_servercategory_destroy(clscrs_crsentity **sc);

clscrs_register_servercategory

The clscrs_register_servercategory API registers the server categories that you specify in the input server category list. The attributes for the server category are contained in the input server category list. The op_status list contains the results of the register operation for each server category and contains no valid attributes. The caller must create and populate the in_entitylist and must create the op_status list. Both of these lists must be destroyed by the caller. The op_status list cannot be reused with another API call. It must be created and destroyed for each API call.

One or more attributes of an already registered server category can be modified by passing the CLSCRS_FLAG_REG_UPDATE flag. The flags apply to all server categories in the input entity list.

clscrs_register_servercategory(clscrs_crsentitylist *in_entitylist, uword flags,
                               clscrs_msgf2 msgf, void *msgarg,
                               clscrs_crsentitylist *op_status);

clscrs_unregister_servercategory

The clscrs_unregister_servercategory API unregisters the server categories that you specify in the input list. The op_status list contains the results of the unregister operation for each server category.

The caller must create and populate the sclist and must create the op_status list. Both of these lists must be destroyed by the caller. The op_status list cannot be reused with another API call and must be created and destroyed for each API call.

clscrs_unregister_servercategory(clscrs_splist *sclist, uword flags,
                                 clscrs_msgf2 msgf, void *msgarg,
                                 clscrs_crsentitylist *op_status);

clscrs_get_server_by_category

The clscrs_get_server_by_category API gets a list of servers that match a particular server category.

clscrs_get_server_by_category(clscrs_splist *in_list,
                              clscrs_crsentitylist *out_entitylist);

clscrs_register_server

The clscrs_register_server API modifies the server attributes. The attributes for the server are contained in the input server list. The op_status list contains the results of the modify operation for each server but contains no valid attributes.

The caller must create and populate the in_entitylist and must create the op_status list. Both of these lists must be destroyed by the caller. The op_status list cannot be reused with another API call and it must be created and destroyed for each API call.

clscrs_register_server(clscrs_crsentitylist *in_entitylist, uword flags,
                       clscrs_msgf2 msgf, void *msgarg,
                       clscrs_crsentitylist *op_status);

clscrs_stat3

The clscrs_stat3 API obtains information about the Oracle Clusterware entities identified in qlist. Information is returned in out_entitylist. Queries are executed such that the subsequent output set is consistent.

You create clscrs_query objects and append them to the clscrs_querylist object before passing the object to this function. Any attributes required for each entity type must be present in the clscrs_query object. If the attribute list is empty, then Oracle Clusterware returns all attributes.

The out_entitylist must be created and passed as an empty list. Any errors for an entity are returned in the out_entitylist.

The output is returned as a nested entity list. Results for individual queries are returned as respective entities in the out_entitylist. The output for individual queries is returned as an entity list for that specific entity. The type of results in the entity can be verified by calling clscrs_crsentity_get_type, to get the Oracle Clusterware entity type of the entity that is part of the out_entitylist.

For example, If you have two queries, one for resources and the other for resource types, then out_entitylist will contain two entity objects, one for each of the aforementioned Oracle Clusterware entity types. The entity list for each of these entity objects will contain the results of the queries. To determine what type of entity object a particular object is, you must call the clscrs_crsentity_get_type function on that entity object. If the query returns zero matches, then the size of the entity list for that entity object will be zero.

clscrs_stat3(clscrs_querylist *qlist,
             uword flags,
             clscrs_crsentitylist *out_entitylist);

clscrs_get_error_details

The clscrs_get_error_details API retrieves and returns the clsk exception stack if there are any failures while invoking other CLSCRS APIs.

clscrs_get_error_details(oratext* error_buf, size_t* buf_size);

clscrs_request_action

The clscrs_request_action API instructs Oracle Clusterware to run an action on a named set of resources. In the first argument, you can specify either a list of resource IDs or a filter. Specifying a filter enables the query and action to take place in a single call. The filter searches all registered resources.

clscrs_request_action(oratext *action_name, clscrs_splist *ridlist,
                      clscrs_env env, clscrs_msgf2 msgf,
                      void *msgarg, uword flag, clscrs_reslist *op_status);

clscrs_stop_resource_in_pools

The clscrs_stop_resource_in_pools API instructs Oracle Clusterware to stop a named set of resources in server pools. Functionality is similar to clscrs_stop_resource2, except that this function takes an extra argument—spoollist—which is a list of server pool names or a filter based on which a list of server pools is generated. This function does not take node as an argument.

clscrs_stop_resource_in_pools(clscrs_splist *ridlist,clscrs_splist *spoollist,
                              clscrs_env env,clscrs_msgf2 msgf2, void *msgarg,
                              uword flags, clscrs_reslist *op_status);

clscrs_start_resource_in_pools

The clscrs_start_resource_in_pools API instructs Oracle Clusterware to start a named set of resources in server pools. Functionality is similar to clscrs_start_resource2, except that this function takes an extra argument—spoollist—which is a list of server pool names or a filter based on which a list of server pools is generated. This function does not take node as an argument.

clscrs_start_resource_in_pools(clscrs_splist *ridlist,clscrs_splist *spoollist,
                               clscrs_env env,clscrs_msgf2 msgf2, void *msgarg,
                               uword flags, clscrs_reslist *op_status);

clscrs_restart_resource

The clscrs_restart_resource API instructs Oracle Clusterware to restart a named set of resources. If the flag is async, then the msgf callback function you specify is never called. The API returns an OK status after initiating the call to Oracle Clusterware, and asynchronously executes the restarts.

If the flag is not async, and msgf is not NULL, then the API drives msgf one line at a time with collected output from the restart programs. An optional event flag maybe passed to indicate that this is not a request to perform an action, but rather a notification that the action has already started. The flag should only be used for a narrow set of co-managed resources.

In the first argument, you can specify either a list of resource IDs or a filter. Specifying a filter enables the query and action to take place in a single call. The filter searches all registered resources.

clscrs_restart_resource(clscrs_splist *ridlist,
                        clscrs_env env, clscrs_msgf2 msgf, void *msgarg,
                        uword flag, clscrs_reslist *op_status);