/* Copyright (c) 2004, 2005, Oracle. All rights reserved. */ /* NAME clscrsx.h - Programming Interface (C API) to Cluster Ready Services DESCRIPTION These APIs provide access to operational control of resources managed by CRS. The API is used to register user applications to the CRS system so that they can be managed by CRS and made Highly Available. Once an application is registered, the application can be started and its state queried. If the application is no longer to be run, it can be stopped and unregistered from CRS. CRS services are provided by another daemon program (crsd) running outside the database server. These APIs communicate with the crsd using an IPC mechanism. EXPORT FUNCTION(S) clscrs_init_crs - init clscrs context clscrs_term_crs - term clscrs context clscrs_getnodename - get nodename for the current node clscrs_register_resource - register resources clscrs_start_resource - start resources clscrs_stat - query resources clscrs_stop_resource - stop resources clscrs_unregister_resource - unregister resources clscrs_sp_set - set the value for a stringpair clscrs_sp_get - get the name and value for a stringpair clscrs_sp_get_value - get the value for a stringpair clscrs_splist_create - create a list of stringpairs (splist) clscrs_splist_create_and_set - creat a splist and add a sp clscrs_splist_append - append a sp clscrs_splist_first - get the first sp in the splist clscrs_splist_next - get the next sp in the splist clscrs_splist_replace - replace the value for a sp clscrs_splist_delete_sp - delete the sp with given name (frees mem) clscrs_splist_find - find the sp matching the given name clscrs_splist_count - count the number of sps in a splist clscrs_splist_destroy - destroy a splist (frees memory) clscrs_res_create - create a resource (res) clscrs_res_get_name - get the name of a resource clscrs_res_set_attr - set an attribute for a resource clscrs_res_get_attr - get the value for the given attribute name clscrs_res_get_attr_list - get the attribute list for a resource clscrs_res_set_attr_list - set the attribute list for a resource clscrs_res_attr_count - count the number of attributes for a res clscrs_res_get_op_status - get the status of an operation on a res clscrs_res_get_node_list - get the hosting members for a resource clscrs_res_destroy - destroy a resource clscrs_reslist_create - create a list of resources (reslist) clscrs_reslist_append - append a resource to a reslist clscrs_reslist_first - get the first resource on the reslist clscrs_reslist_next - get the next resource on the reslist clscrs_reslist_find - find the resource matching the given name clscrs_reslist_count - count the number of resources in the list clscrs_reslist_delete_res - delete the resource matchine the given name clscrs_reslist_destroy - destory a resource list clscrs_get_fixed_attrlist - get the list of attributes corresponding to an attribute group identifier clscrs_res_get_registered - find out if the resource is registered EXAMPLES Refer to the demo application /crs/demo/crsapp.c NOTES clscrs_sp: This is a stringpair (sp) structure. It contains a name and a value string. The value may be NULL. It is created and destroyed, and its contents can be examined and the value replaced. A 'sp' may 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. Sometimes the list contains names and values, sometimes only names. It is created and destroyed; members can be retrieved by name, added, deleted, replaced, and the list can be traversed with the "first" and "next" operations. clscrs_res: This represents a resource abstraction which contains the name of a resource, and additional data appropriate to the context in which it is used. Sometimes it contains resource attribute data and othertimes it carries status and return message about an operation. A resource may be in exactly one resource list. clscrs_reslist: A resource list is an abstraction used to contain information about zero or more resources. A resource list is created, appended, iterated over, and destroyed. The above list structures should not be shared across threads in a multithreaded application. The list manipulation routines are not thread-safe. MODIFIED (MM/DD/YY) rdasari 05/06/05 - document CLSCRS_FLAG_USETHREADS rdasari 03/23/05 - add new attribute UPTIME_THRESHOLD agusev 10/29/04 - Adding comments for the new flag agusev 10/27/04 - Adding the EVENT flag rdasari 08/03/04 - rdasari_api_app rdasari 07/27/04 - Creation */ #ifdef __cplusplus extern "C" { #endif #ifndef ORATYPES # include #endif #ifndef CLSCRSX_ORACLE # define CLSCRSX_ORACLE /* Return codes for the CLSCRS api */ typedef enum { CLSCRS_STAT_SUCCESS=0, /* "Command Success" */ CLSCRS_STAT_CONTINUE, /* try again */ CLSCRS_STAT_CONNECTION=184, /* Cannot communicate with crsd */ CLSCRS_STAT_WARNING=199, /* "Catch all warning. No reason provided" */ CLSCRS_STAT_FAILURE=200, /* "Catch all failure. No reason provided" */ CLSCRS_STAT_BAD_COMMAND=201, /* "Catch all failure. No reason provided" */ CLSCRS_STAT_NO_APPS=202, /* "No resources are registered" */ CLSCRS_STAT_OTHER=203, /* "To be supplied" */ CLSCRS_STAT_APP_NAME=210, /* "Could not find resource" */ CLSCRS_STAT_IS_REGISTERED=211, /* "Resource has already been registered" */ CLSCRS_STAT_NOT_REGISTERED=212, /* "Resource is not registered" */ CLSCRS_STAT_REGISTER_FAIL=213, /* "Could not register resource" */ CLSCRS_STAT_UNREGISTER_FAIL=214, /* "Could not unregister resource" */ CLSCRS_STAT_START_FAIL=215, /* "Could not start resource" */ CLSCRS_STAT_STOP_FAIL=216, /* "Could not stop resource" */ CLSCRS_STAT_RELOCATE_FAIL=217, /* "Could not relocate resource" */ CLSCRS_STAT_NOT_RESTART=218, /* "Could not restart resource" */ CLSCRS_STAT_UPDATE_FAIL=219, /* cannot update the resource. */ CLSCRS_STAT_PROFILE_INVALID=220, /* Your profile was invalid */ CLSCRS_STAT_PROFILE_BADPATH=221, /* The profile was not found on disk */ CLSCRS_STAT_DEPENDENCY=222, /* dependency problem. */ CLSCRS_STAT_PLACEMENT=223, /* placement problem. */ CLSCRS_STAT_SCRIPT_OUTPUT=224, /* Warning: failed to redirect IO */ CLSCRS_STAT_MISSING_RESNAME = 225, /* Resource name not specified. */ CLSCRS_STAT_MEMALLOC_WARNING = 226, /* Internal memory allocation warning. */ CLSCRS_STAT_INVALID_RESNAME = 227, /* Invalid Resource name. */ CLSCRS_STAT_INVALID_HOST = 228, /* Invalid Hostname. */ CLSCRS_STAT_INVALID_FLAGS = 229, /* "Invalid combination of flags" */ CLSCRS_STAT_MEMBER_INVALID=230, /* member is not a cluster member */ CLSCRS_STAT_OPERATION_INVALID=231,/* "operation invalid for resource type" */ CLSCRS_STAT_MEMBER_DOWN=232, /* member is down */ CLSCRS_STAT_RESOURCE_BUSY=233, /* resource is busy */ CLSCRS_STAT_USEROPTS_INVALID=234, /* User supplied attribs not in profile */ /* above ends the 9.2 set of messages */ CLSCRS_STAT_INVALID=239, /* Invalid command */ CLSCRS_STAT_CHANNEL_OUTPUT=240, /* Piped channel output error */ CLSCRS_STAT_INVALID_DIRPATH=241, /* Invalid directory path. */ CLSCRS_STAT_ACL_UNAVAILABLE = 242, /* ACL information is not available */ CLSCRS_STAT_DEFAULT_SETTING_UNAVAILABLE = 243,/*default setting unavailable */ CLSCRS_STAT_REGISTER_UNAVAILABLE = 244, /* registration allow/deny */ /* information is not available */ CLSCRS_STAT_NO_PRIVILEGE = 245, /* User doesn't have enough privilege to */ /* perform the operation */ CLSCRS_STAT_INVALID_ID = 246, /* User id is invalid */ CLSCRS_STAT_INVALID_NAME = 247, /* User name is invalid */ CLSCRS_STAT_ACL_FAILED = 248, /* Acl operation failed */ CLSCRS_STAT_AUTHENTICATION_FAILURE=249, /* authentication failure. */ CLSCRS_STAT_CONFIGURE_FAILURE=250,/* Configuration unsuccessful. Try again */ /* or restart caads. */ CLSCRS_STAT_CONFIGURATION_MISS=251, /* CAA configuration file missing. */ CLSCRS_STAT_CONFIGURATION_ERROR=252, /* CAA configuration file syntax */ /* error. */ CLSCRS_STAT_MISSING_USR_DEF_DIR=253, /* USER_DEFAULT_DIR is not set in */ /* CAA configuration file. */ CLSCRS_STAT_AUTHORIZATION_FAILURE=254, /* authorization failure */ /* Do not specify return codes exceeding 255 for CRS */ /* messages 301 - 324 in use */ /* messages 325 - 350 Client side resource validation */ CLSCRS_STAT_RESNAME_MISMATCH=325, CLSCRS_STAT_INVALID_RESTYPE=326, CLSCRS_STAT_MISSING_ATTR=327, CLSCRS_STAT_ACTSCR_NOTEXIST=328, CLSCRS_STAT_HOSTMEM_REQ=329, CLSCRS_STAT_HOSTMEM_NOTREQ=330, CLSCRS_STAT_INVALID_HOSTMEM=331, CLSCRS_STAT_INVALID_PLACEMENT=332, CLSCRS_STAT_INVALID_AUTOSTART=333, CLSCRS_STAT_INVALID_VALUE=334, /* messages 401 - 420 in use */ CLSCRS_STAT_CSSINIT_FAILED=413, /* CSS init failed */ /* Messages 451 - 470 OCR related */ CLSCRS_STAT_NO_OCR=451, /* "Can't find initialize OCR" */ CLSCRS_STAT_NO_CRSD_CONN=452, /* "Can't find crsd conn in OCR" */ CLSCRS_STAT_INST_NOT_ENABLED = 453, /* Instance is not enabled */ /* Messages 471 - 500 CSS related */ CLSCRS_STAT_CSS_NO_NODE_NUM=471, /* css api unable to get the node number */ CLSCRS_STAT_CSS_NO_NODE_NAME=472 /* css could not retrieve the node name */ /* messages 1001 -1028 in use */ /* messages 2001 - 2020 in use */ } CLSCRS_STAT; /* Return codes for the clscrs_sp, clscrs_splist, clscrs_res, clscrs_reslist funtions */ typedef enum clscrsret { clscrsretSUCC = 0, /* Success */ clscrsretFAIL = 1, /* Failure */ clscrsretNOMEM = 2, /* Memory Allocation Failure */ clscrsretBADCTX = 3, /* Invalid clscrs context */ clscrsretBADARG = 4, /* Invalid argument */ clscrsretNONAME = 5, /* Given name not found */ clscrsretENDLIST = 6, /* End of list reached */ clscrsretNOATTRS = 7, /* No attributes set for the resource */ clscrsretNOMSG = 8, /* No error message available */ clscrsretNORES = 9, /* Given resource not found */ clscrsretRESEXISTS = 10, /* Resource already exists */ clscrsretEMPTY = 11, /* List is empty */ clscrsretBADRESNAME = 12 } clscrsret; /* Resource Attributes */ #define clscrs_NAME ((oratext*)"NAME") #define clscrs_TYPE ((oratext*)"TYPE") #define clscrs_ACTION_SCRIPT ((oratext*)"ACTION_SCRIPT") #define clscrs_ACTIVE_PLACEMENT ((oratext*)"ACTIVE_PLACEMENT") #define clscrs_AUTO_START ((oratext*)"AUTO_START") #define clscrs_CHECK_INTERVAL ((oratext*)"CHECK_INTERVAL") #define clscrs_DESCRIPTION ((oratext*)"DESCRIPTION") #define clscrs_FAILOVER_DELAY ((oratext*)"FAILOVER_DELAY") #define clscrs_FAILURE_INTERVAL ((oratext*)"FAILURE_INTERVAL") #define clscrs_FAILURE_THRESHOLD ((oratext*)"FAILURE_THRESHOLD") #define clscrs_HOSTING_MEMBERS ((oratext*)"HOSTING_MEMBERS") #define clscrs_OPTIONAL_RESOURCES ((oratext*)"OPTIONAL_RESOURCES") #define clscrs_PLACEMENT ((oratext*)"PLACEMENT") #define clscrs_REQUIRED_RESOURCES ((oratext*)"REQUIRED_RESOURCES") #define clscrs_RESTART_ATTEMPTS ((oratext*)"RESTART_ATTEMPTS") #define clscrs_SCRIPT_TIMEOUT ((oratext*)"SCRIPT_TIMEOUT") #define clscrs_START_TIMEOUT ((oratext*)"START_TIMEOUT") #define clscrs_STOP_TIMEOUT ((oratext*)"STOP_TIMEOUT") #define clscrs_UPTIME_THRESHOLD ((oratext*)"UPTIME_THRESHOLD") #define clscrs_STATE ((oratext*)"STATE") #define clscrs_TARGET ((oratext*)"TARGET") #define clscrs_ENABLED ((oratext*)"ENABLED") #define clscrs_EXISTS ((oratext*)"EXISTS") /* Structure containing clscrs "global" context */ typedef struct clscrs_ctx clscrs_ctx; /* Structure representing a resource */ typedef struct clscrs_res clscrs_res; /* Structure for a list of resources */ typedef struct clscrs_reslist clscrs_reslist; /* Structure representing a stringpair */ typedef struct clscrs_sp clscrs_sp; /* Structure for a list of stringpairs */ typedef struct clscrs_splist clscrs_splist; /* Structure for passing enviornment variables to start and stop operations */ typedef struct clscrs_env_item *clscrs_env; /* Enum for specifying the list of attributes queried in the clscrs_stat api */ typedef enum { clscrs_attrs_none = 1, clscrs_attrs_all = 2, clscrs_attrs_short = 3, clscrs_attrs_state = 4 } clscrs_attr_grp; /* Environment operation status domain. */ typedef enum { CLSCRS_ENV_SUCCESS=0, CLSCRS_ENV_SYNTAX=101, CLSCRS_ENV_VALUE=102, CLSCRS_ENV_ATTR_NOTFOUND=103, CLSCRS_ENV_NULL=104, CLSCRS_ENV_FAILURE=105 } CLSCRS_ENVCODE; /* Flags passed to the clscrs context initialization routine clscrs_init_crs() */ typedef enum { /* default flag */ CLSCRS_FLAG_NONE=0, /* flag for asynchronous execution of the api. The call will return before the request is processed completely */ CLSCRS_FLAG_ASYNC=0x01, /* flag for synchronous execution of the api. The call will return after the request is processed completely */ CLSCRS_FLAG_FORCE=0x02, /* flag to enable tracing via the callback function */ CLSCRS_FLAG_TRACE=0x04, /* flag to enable multithreading. This flag will enable the use of the clscrs context in mutliple threads. The context should be initialized while the application is single-threaded. */ CLSCRS_FLAG_USETHREADS=0x08, /* flag passed to register api for updating the attributes of an already registered resource */ CLSCRS_FLAG_REG_UPDATE=0x10, /* flag passed to start and stop api to indicate the start/stop event rather than a request to run the start/stop actions */ CLSCRS_FLAG_EVENT=0x20 } CLSCRS_FLAG; #define CLSCRS_ATTRS_NONE(ctx) \ (clscrs_get_fixed_attrlist(ctx, clscrs_attrs_none)) #define CLSCRS_ATTRS_ALL(ctx) \ (clscrs_get_fixed_attrlist(ctx, clscrs_attrs_all)) #define CLSCRS_ATTRS_STATE(ctx) \ (clscrs_get_fixed_attrlist(ctx, clscrs_attrs_state)) #define CLSCRS_ATTRS_SHORT(ctx) \ (clscrs_get_fixed_attrlist(ctx, clscrs_attrs_short)) /*--------------------------------------------------------------------------- PRIVATE TYPES AND CONSTANTS ---------------------------------------------------------------------------*/ /*--------------------------------------------------------------------------- EXPORT FUNCTIONS ---------------------------------------------------------------------------*/ /* ---------------------------- clscrs_msgf ---------------------------- */ /* NAME clscrs_msgf DESCRIPTION User function called to deliver output text from CRS operations. PARAMETERS usrp -- user supplied pointer, probably containing context of the call. msg -- output text msglen -- length of the output text. RETURNS none */ typedef void (*clscrs_msgf)(void *usrp, const oratext *msg, sword msglen); /* ------------------------- clscrs_init_crs ---------------------------- */ /* NAME clscrs_init_crs DESCRIPTION Initializes a context for communications with CRS. The context should be initialized before spawning any threads in the application. PARAMETERS ctx -- context to initialize, function allocates storage. errf -- callback func for the error info, or NULL errCtx -- Context for the error callback func, or NULL flags -- CLSCRS_FLAG_TRACE, to enable tracing of lower layers CLSCRS_FLAG_USETHREADS, to enable using the context in multiple threads. RETURNS status */ CLSCRS_STAT clscrs_init_crs(clscrs_ctx **ctx, clscrs_msgf errf, void *errCtx, ub4 flags); /* ---------------------------- clscrs_term_crs ---------------------------- */ /* NAME clscrs_term_crs DESCRIPTION Releases a context for communications with CRS. PARAMETERS ctx -- context previously initialized with clscrs_init_crs. RETURNS status */ CLSCRS_STAT clscrs_term_crs(clscrs_ctx **ctx); /* ------------------------ clscrs_env_create ---------------------------- */ /* NAME clscrs_env_create DESCRIPTION Creates a call environment describing parameters to CRS calls. The memory is owned by clscrs, release env clscrs_env_delete PARAMETERS context -- input context env -- output env pointer. RETURNS status enum */ CLSCRS_STAT clscrs_env_create( clscrs_ctx *ctx, clscrs_env *env ); /* ---------------------------- clscrs_env_set ---------------------------- */ /* NAME clscrs_env_set DESCRIPTION Sets an attribute/value argument in an environment for CRS calls; val may be null. PARAMETERS env -- previously created environment attr -- attribute name val -- attribute value, may be null pointer. RETURNS environment status enum */ CLSCRS_ENVCODE clscrs_env_set( clscrs_env env, const oratext *attr, const oratext *val); /* -------------------------- clscrs_env_delete ---------------------------- */ /* NAME clscrs_env_delete DESCRIPTION Deletes an environment for CRS calls. The environment must be created again before use. You may not delete it and then set new parameters. PARAMETERS env -- the environment whose contents are deleted. RETURNS environment status enum. */ CLSCRS_ENVCODE clscrs_env_delete( clscrs_env env ); /* ---------------------------- clscrs_env_format ------------------------- */ /* NAME clscrs_env_format DESCRIPTION Drive a callback with formatted environment lines. PARAMETERS env -- env to dump msgf -- callback function msgp -- argument to msgp, uninterpreted. RETURNS NOTES MODIFIED (MM/DD/YY) dbrower 08/26/02 - created. */ void clscrs_env_format(clscrs_env env, clscrs_msgf msgf, void *msgp); /* ---------------------------- clscrs_getnodename ------------------------- */ /* NAME clscrs_getnodename DESCRIPTION Function for getting the nodename; if in a configured cluster, this is the name as known to the clusterware. If not in a cluster, the name as known through other OSD means. Getting a node name may be expensive in the first call, especially if CLSCRS was not initialized with a pre-existing CSS context. PARAMETERS ctx [in] clscrs context nodename [out] name of the local node RETURNS status */ CLSCRS_STAT clscrs_getnodename(clscrs_ctx *ctx, oratext *nodename); /* ---------------------------- clscrs_get_crshome ------------------------- */ /* NAME clscrs_get_crshome DESCRIPTION This function returns the path for ORA_CRS_HOME. PARAMETERS ctx [in] clscrs context crshome [out] path for ORA_CRS_HOME bufsize [in] size of the buffer for crshome RETURNS status */ CLSCRS_STAT clscrs_get_crshome(clscrs_ctx *ctx, oratext *crshome, size_t *bufsize); /* --------------------- clscrs_register_resource -------------------------- */ /* NAME clscrs_register_resource DESCRIPTION Register the resources in the input resource list. The attributes for the resources are encapsulated in the input resource list. The output op_status list contains the results of the register operation for each resource, and contains no valid resource attributes. The caller must create and populate the in_reslist and must create the op_status list. Both the 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 resource can be modified by passing the CLSCRS_FLAG_REG_UPDATE flag. The flags apply to all resources in the input reslist. PARAMETERS in_reslist [in] - list of resources to be registered flags [in] - CLSCRS_FLAG_REG_UPDATE or 0. op_status [out] - resource list holding the status of the register operation for each resource. RETURNS CLSCRS_STAT_SUCCESS if all input resources are successfully registered CLSCRS_STAT_FAIL if atleast one resource could not be registered CLSCRS_STAT_CONNECTION if there is a communication error with the crsd */ CLSCRS_STAT clscrs_register_resource(clscrs_reslist *in_reslist, uword flags, clscrs_reslist *op_status); /* ------------------------ clscrs_unregister_resource --------------------- */ /* NAME clscrs_unregister_resource DESCRIPTION Unregister the resources in the input list of resource names. The output op_status list contains the results of the unregister operation for each resource. The caller must create and populate the rqlist and must create the op_status list. Both the 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. PARAMETERS rqlist [in] - list of resources names to be unregistered flags [in] - option flags op_status [out] - resource list holding the status of the unregister operation for each resource. RETURNS CLSCRS_STAT_SUCCESS if all input resources are successfully unregistered CLSCRS_STAT_FAIL if atleast one resource could not be unregistered CLSCRS_STAT_CONNECTION if there is a communication error with the crsd */ CLSCRS_STAT clscrs_unregister_resource(clscrs_splist *rqlist, uword flags, clscrs_reslist *op_status); /* ------------------------------- clscrs_stat ---------------------------- */ /* NAME clscrs_stat DESCRIPTION Get information about the resources identified in rqlist. The resources can be restricted to a specific node given in the nodename parameter. The information is returned in the output out_reslist. If the rqlist is NULL, information about all registered resources is returned. If the nodename is not NULL, the result is restricted to resources running on the specific node. Otherwise, all nodes in the cluster are considered. The res_flags are used to scope the resource domain that is matched. There are currently no values for this parameter. In the future, it may ne used to get all resources in a dependency tree or resources that meet some attribute predicates - e.g.,resources that are disabled, running etc. The res_attrs identifies the attributes to be returned in the out_reslist. The caller may create a specific list of attributes of interest or use a pre-defined list returned by one of the macros CLSCRS_ATTRS_NONE, CLSCRS_ATTRS_ALL, CLSCRS_ATTRS_STATE, CLSCRS_ATTRS_SHORT. The attribute list applies to all resources identified by the rqlist. Any errors for a resource are returned in the output out_reslist. PARAMETERS rqlist [in] list of resource names to query nodename [in] query resources running only on the given node (optional, may be NULL) res_flags [in] flags to restrict the resources being matched res_attrs [in] list to specify the attributes to be returned for each resource out_reslist [out] list holding the returned resource information RETURNS CLSCRS_STAT_SUCCESS if information is got for all input resources CLSCRS_STAT_FAIL if no information is available for atleast one resource CLSCRS_STAT_CONNECTION if there is an error communicating with the crsd */ CLSCRS_STAT clscrs_stat(clscrs_splist *rqlist, oratext *nodename, uword res_flags, clscrs_splist *res_attrs, clscrs_reslist *out_reslist); /* ---------------------- clscrs_start_resource ---------------------------- */ /* NAME clscrs_start_resource DESCRIPTION Tell the CRS system to start a named set of resources. If node is specified, start there, otherwise according to the placement policy for the resources in question. If the flag is async, msgf will never be called, and OK status will be returned after initiating the call to the CRS system, and the actual starts will be asynchronously executed, and msgf will never be called. If flag is not async, and msgf is not null, msgf will be driven line at a time with collected output from the start programs. An optional EVENT flag maybe passed in to indicate that this this 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. PARAMETERS ctx [in] clscrs context names [in] name of resource(s) to start num_names [in] number of resources in names[] above node [in] the nodename on which to start the resource, may be null env [in] environment arguments to the start operation msgf [in] user message callback, may be null. msgp [in] user callback argument, may be null. flag [in] async, force, event options. RETURNS status enum */ CLSCRS_STAT clscrs_start_resource(clscrs_ctx *ctx, const oratext *name[], sword num_names, const oratext *node, clscrs_env env, clscrs_msgf msgf, void *msgp, uword flag); /* ----------------------- clscrs_stop_resource ---------------------------- */ /* NAME clscrs_stop_resource DESCRIPTION Tell the CRS system to stop a named set of resources. The flag allows async stop. PARAMETERS ctx [in] clscrs context names [in] name of resource(s) to stop num_names [in] number of resources in names[] above env [in] environment arguments to the stop operation msgf [in] user message callback, may be null. msgp [in] user callback argument, may be null. flag [in] async, force, event options. RETURNS status enum */ CLSCRS_STAT clscrs_stop_resource(clscrs_ctx *ctx, const oratext *names[], sword num_names, clscrs_env env, clscrs_msgf msgf, void *msgarg, uword flag); /* ------------------------ clscrs_fail_resource --------------------------- */ /* NAME clscrs_fail_resource DESCRIPTION Tells CRS to act as if the identified resources in rqlist have failed, without running their check actions. The failure is always asynchronous with respect to the caller as are the recovery actions performed by the CRSD. The expanded resources are identified and sent back to the caller in the op_status list, containing the status of the lookup and permission check of each matching resource. A resource that is explicitly named with no pattern matching will have a NOTFOUND error. A pattern that has no matches will return no error. There will be no valid attributes returned for the resources. Errors will also be returned if the caller does not have permission to operate on the matching resources. Returns SUCCESS if the operation status of all identified resources is SUCCESS, otherwise FAILURE. PARAMETERS ctx [in] clscrs context rqlist [in] list of the resources to fail. flags [in] none. op_status [out] resource list structure holding the status of the fail operation for each resource. RETURNS status enum. */ CLSCRS_STAT clscrs_fail_resource( clscrs_splist *in_splist, uword flags, clscrs_reslist *op_status); /* ----------------------- clscrs_check_resource --------------------------- */ /* NAME clscrs_check_resource DESCRIPTION Tell CRS to run the check actions for the identified resources. A delay can be specified in the indicating a time to wait in seconds before the check action is fired in the server, after the call returns. This can be used to let something run before doing the check. For each resource identified by the rqlist, a status will be returned in the op_status, indicating whether the resource exists and whether the caller has permission to invoke operations on the resource. A resource that is explicitly named with no pattern matching will have a NOTFOUND error. A pattern that has no matches will return no error. There will be no valid attributes returned for the resources. There is no way of knowing exactly when the checks will actually be run or be completed. Returns SUCCESS if the operation status of all identified resources is SUCCESS, otherwise FAILURE and specific status will be found in the op_status entries. The caller must create the op_status list before the call, and destroy it when done. Parameters: ctx [in] clscrs context rqlist [in] list of resources to check delay_secs [in] time to wait before the check is run, as appropriate to the resource flags [in] none. op_status [out] resource list structure holding the status of the fail operation for each resource. RETURNS status enum. */ CLSCRS_STAT clscrs_check_resource( clscrs_splist *in_splist, ub4 delay_seconds, uword flags, clscrs_reslist *op_status); /*************************** stringpair functions **************************/ /* The stringpair and list manipulation functions are not thread safe. Thus, the structures cannot be shared across threads */ /* NAME clscrs_sp_set DESCRIPTION Change the value part of a stringpair. The new value may be NULL. After the call returns, the memory of the value can be recycled. PARAMETERS sp [in] - stringpair to set the value for value [in] - value component of the stringpair (may be NULL) RETURNS clscrsretSUCC on success clscrsretBADARG if the sp argument is null */ clscrsret clscrs_sp_set(clscrs_sp *sp, const oratext *value); /* NAME clscrs_sp_get PURPOSE Get the name and value components of a stringpair. PARAMETERS sp [in] - stringpair for which the name and value are being get name [out] - name component of the stringpair value [out] - value component of the stringpair (may be NULL) RETURNS clscrsretSUCC on success clscrsretNOMEM if no memory can be allocated clscrsretBADARG if the sp argument is null */ clscrsret clscrs_sp_get(clscrs_sp *sp, oratext **name, oratext **value); /* NAME clscrs_sp_get_value PURPOSE Get the value component of a stringpair. PARAMETERS sp [in] - stringpair for which the name and value are being get value [out] - value component of the stringpair (may be NULL) RETURNS clscrsretSUCC on success clscrsretBADARG if the sp argument is null */ clscrsret clscrs_sp_get_value(clscrs_sp *sp, oratext **value); /***************************** splist functions ***************************/ /* NAME clscrs_splist_create DESCRIPTION Create a new stringpair list. The memory for the splist is allocated by the function. PARAMETERS ctx [in] - clscrs context splist [out] - the new stringpair list created RETURNS clscrsretSUCC on success clscrsretNOMEM if no memory can be allocated clscrsretBADCTX if the context is null */ clscrsret clscrs_splist_create(clscrs_ctx *ctx, clscrs_splist **splist); /* NAME clscrs_splist_create_and_set DESCRIPTION Create a new stringpair list (splist) and set the name and value for the first stringpair in the list. The memory for the splist is allocated by the function. PARAMETERS ctx [in] - clscrs context name [in] - name component of the stringpair value [in] - value component of the stringpair (may be NULL) sp [out] - the new stringpair created RETURNS clscrsretSUCC on success clscrsretNOMEM if no memory can be allocated clscrsretBADCTX if the context is null clscrsretBADARG if the name argument is null */ clscrsret clscrs_splist_create_and_set(clscrs_ctx *ctx, const oratext *name, const oratext *value, clscrs_splist **splist); /* NAME clscrs_splist_append DESCRIPTION Add a new stringpair (sp) to a stringpair list (splist). PARAMETERS splist [in] - splist to add the new {name, value} stringpair. name [in] - name component of the stringpair value [in] - value component of the stringpair (may be NULL) RETURNS clscrsretSUCC on success clscrsretNOMEM if no memory can be allocated clscrsretBADARG if the name argument is null */ clscrsret clscrs_splist_append(clscrs_splist *splist, const oratext *name, const oratext *value); /* NAME clscrs_splist_first DESCRIPTION Get the first stringpair (sp) from a stringpair list (splist). PARAMETERS splist [in] - splist to get the first sp from. sp [out] - the first sp from the given splist. RETURNS clscrsretSUCC on success clscrsretBADARG if the splist is null clscrsretEMPTY if there are no stringpair elements in the splist */ clscrsret clscrs_splist_first(clscrs_splist *splist, clscrs_sp **sp); /* NAME clscrs_splist_next DESCRIPTION Get the current next stringpair (sp) from a stringpair list (splist). This function is called to iterate over the stringpairs in a splist. PARAMETERS splist [in] - splist to get the next sp from. sp [out] - the next sp {name, value} in the given splist. RETURNS clscrsretSUCC on success clscrsretBADARG if the splist is null clscrsretENDLIST if there are no more stringpair elements in the splist */ clscrsret clscrs_splist_next(clscrs_splist *splist, clscrs_sp **sp); /* NAME clscrs_splist_replace DESCRIPTION Replace the value for a stringpair (sp) in a stringpair list (splist). PARAMETERS splist [in] - splist to add the new {name, value} stringpair. name [in] - name for which the value is being replaced. value [in] - replacement value for the name (may be NULL) RETURNS clscrsretSUCC on success clscrsretNONAME if there is no stringpair matching the given name clscrsretBADARG if the name argument is null */ clscrsret clscrs_splist_replace(clscrs_splist *splist, const oratext *name, const oratext *value); /* NAME clscrs_splist_delete_sp DESCRIPTION Delete a stringpair (sp) from a stringpair list (splist). PARAMETERS splist [in] - splist from which to delete the {name, value} stringpair. name [in] - name to be deleted from the given splist. RETURNS clscrsretSUCC on success clscrsretNONAME if there is no stringpair matching the given name clscrsretBADARG if the name argument is null */ clscrsret clscrs_splist_delete_sp(clscrs_splist *splist, const oratext *name); /* NAME clscrs_splist_find DESCRIPTION Find the value for a stringpair (sp) in a stringpair list (splist). PARAMETERS splist [in] - splist to look into name [in] - name for which the value is looked up. value [out] - value associated with the given name in the given splist RETURNS clscrsretSUCC on success clscrsretNONAME if there is no stringpair matching the given name clscrsretBADARG if the name argument is null */ clscrsret clscrs_splist_find(clscrs_splist *splist, const oratext *name, oratext **value); /* NAME clscrs_splist_count DESCRIPTION Count the number of stringpairs (sp) in a stringpair list (splist). PARAMETERS splist [in] - splist to count the number of stringpairs. count [out] - the number of stringpairs in the given splist. RETURNS clscrsretSUCC on success clscrsretBADARG if the splist is null */ clscrsret clscrs_splist_count(clscrs_splist *splist, ub4 *count); /* NAME clscrs_splist_destroy DESCRIPTION Free the memory for a stringpair list (splist). PARAMETERS splist [in] - splist to destroy RETURNS clscrsretSUCC on success */ clscrsret clscrs_splist_destroy(clscrs_splist **splist); /**************************** resource functions ***********************/ /* NAME clscrs_res_create DESCRIPTION Create a new resource. The memory for the resource structure is allocated by the function. The memory is freed when a resource list (clscrs_reslist) is destroyed through clscrs_reslist_destroy(). PARAMETERS ctx [in] - clscrs context resname [in] - name of the resource res [out] - the new resource created RETURNS clscrsretSUCC on success clscrsretNOMEM if no memory can be allocated clscrsretBADCTX if the context is null clscrsretBADARG if the resource name is null */ clscrsret clscrs_res_create(clscrs_ctx *ctx, const oratext *resname, clscrs_res **res); /* NAME clscrs_res_get_name DESCRIPTION Get the name of a resource. PARAMETERS res [in] - resource for which the name is got name [out] - name of the resource RETURNS clscrsretSUCC on success clscrsretBADARG if the resource argument is null */ clscrsret clscrs_res_get_name(clscrs_res *res, oratext **name); /* NAME clscrs_res_set_attr DESCRIPTION Set a resource attribute for a resource. PARAMETERS res [in] - resource for which the attribute is set attrname [in] - name of the resource attribute value [in] - value for the resource attribute (may be NULL) RETURNS clscrsretSUCC on success clscrsretBADARG if the attribute name is null clscrsretNOMEM if no memory can be allocated */ clscrsret clscrs_res_set_attr(clscrs_res *res, const oratext *attrname, const oratext *value); /* NAME clscrs_res_get_attr DESCRIPTION Get a resource attribute for a resource. PARAMETERS res [in] - resource for which the attribute is got attrname [in] - name of the resource attribute value [out] - value for the resource attribute RETURNS clscrsretSUCC on success clscrsretBADARG if the attribute name is null clscrsretNOMEM if no memory can be allocated */ clscrsret clscrs_res_get_attr(clscrs_res *res, const oratext *attrname, oratext **value); /* NAME clscrs_res_get_attr_list DESCRIPTION Get the attribute list for a resource. The attribute list is a list of stringpairs. The client does not allocate the memory for attrlist. PARAMETERS res [in] - resource for which the attribute list is got attrlist [out] - list of attributes for the given resource RETURNS clscrsretSUCC on success clscrsretBADARG if the resource is null clscrsretNOMEM if no memory can be allocated clscrsretNOATTRS if there are no attributes set for the resource */ clscrsret clscrs_res_get_attr_list(clscrs_res *res, clscrs_splist **attrlist); /* NAME clscrs_res_set_attr_list DESCRIPTION Set the attribute list for a resource. The attribute list is a list of stringpairs. The list is created from the clscrs_splist_create call. PARAMETERS res [in] - resource for which the attribute list is set attrlist [in] - list of attributes to be set for the given resource RETURNS clscrsretSUCC on success clscrsretBADARG if the resource is null */ clscrsret clscrs_res_set_attr_list(clscrs_res *res, clscrs_splist *attrlist); /* NAME clscrs_res_attr_count DESCRIPTION Get the number of attributes for a resource. PARAMETERS res [in] - resource for which number of attributes is got count [out] - number of attributes for the given resource RETURNS clscrsretSUCC on success clscrsretBADARG if the resource is null */ clscrsret clscrs_res_attr_count(clscrs_res *res, ub4 *count); /* NAME clscrs_res_get_op_status DESCRIPTION Get the status of an operation for a resource. The memory for the msg is allocated by the function. PARAMETERS res [in] - resource for which the operation status is got status [out] - status of an operation on the given resource msg [out] - text message for the result of an operation on the resource RETURNS clscrsretSUCC on success clscrsretNOMEM if no memory can be allocated clscrsretNOMSG if there is no msg available clscrsretBADARG if the resource is null */ clscrsret clscrs_res_get_op_status(clscrs_res *res, CLSCRS_STAT *status, oratext **msg); /* NAME clscrs_res_get_registered DESCRIPTION Get the registration status of a resource. PARAMETERS res [in] - resource for which the operation status is set registered [out] - boolean indicating whether the resource is registered RETURNS clscrsretSUCC on success clscrsretNOMEM if no memory can be allocated clscrsretBADARG if the resource is null */ clscrsret clscrs_res_get_registered(clscrs_res *res, boolean *registered); /* NAME clscrs_res_get_node_list DESCRIPTION Get the nodelist currently hosting the resource, or NULL if there is no host for the resource or there are no attributes. The caller need not allocate memory for the nodelist. PARAMETERS res [in] - resource for which the nodelist is got nodelist [out] - splist holding the node(s) RETURNS clscrsretSUCC on success clscrsretBADARG if the resource is null */ clscrsret clscrs_res_get_node_list(clscrs_res *res, clscrs_splist **nodelist); /* NAME clscrs_res_destroy DESCRIPTION Free the memory for a resource. PARAMETERS res [in] - resource for which the memory is freed RETURNS clscrsretSUCC on success */ clscrsret clscrs_res_destroy(clscrs_res **res); /************************* reslist functions ******************************/ /* NAME clscrs_reslist_create DESCRIPTION Create a new resource list. The memory for the resource list is allocated by the function. PARAMETERS ctx [in] - clscrs context reslist [out] - resource list (empty) that is created RETURNS clscrsretSUCC on success clscrsretNOMEM if no memory can be allocated clscrsretBADCTX if the context is null */ clscrsret clscrs_reslist_create(clscrs_ctx *ctx, clscrs_reslist **reslist); /* NAME clscrs_reslist_append DESCRIPTION Add a resource to a resource list. PARAMETERS reslist [in] - resource list to add the resource to res [in] - resource to add RETURNS clscrsretSUCC on success clscrsretBADARG if reslist is null clscrsretRESEXISTS if the resource already exists in reslist */ clscrsret clscrs_reslist_append(clscrs_reslist *reslist, clscrs_res *res); /* NAME clscrs_reslist_first DESCRIPTION Get the first resource on a resource list. PARAMETERS reslist [in] - resource list for which the first resource is got res [out] - the first resouce on the resource list RETURNS clscrsretSUCC on success. clscrsretBADARG if reslist is null clscrsretEMPTY if there are no resources in the list */ clscrsret clscrs_reslist_first(clscrs_reslist *reslist, clscrs_res **res); /* NAME clscrs_reslist_next DESCRIPTION Get the current next resource from the resource list. This function is called to iterate over the resources in a resource list. PARAMETERS reslist [in] - resource list for which the first resource is got res [out] - the next resouce on the resource list RETURNS clscrsretSUCC on success clscrsretBADARG if reslist is null clscrsretENDLIST if there are no more resources in the list */ clscrsret clscrs_reslist_next(clscrs_reslist *reslist, clscrs_res **res); /* NAME clscrs_reslist_find DESCRIPTION Find a resource in a resource list. PARAMETERS reslist [in] - resource list (empty) that is created name [in] - name of the resource that is being get res [out] - the resouce corresponding to the given name RETURNS clscrsretSUCC on success clscrsretNORES if the resource is not found clscrsretBADARG if reslist or name is null */ clscrsret clscrs_reslist_find(clscrs_reslist *reslist, const oratext *name, clscrs_res **res); /* NAME clscrs_reslist_count DESCRIPTION Count the number of resources in a resource list. PARAMETERS reslist [in] - resource list for which the count is got count [out] - number of resources in the resource list RETURNS clscrsretSUCC on success clscrsretBADARG if reslist is null */ clscrsret clscrs_reslist_count(clscrs_reslist *reslist, ub4 *count); /* NAME clscrs_reslist_delete_res DESCRIPTION Delete a resource from a resource list. PARAMETERS reslist [in] - resource list from which to delete the resource name [in] - name of the resource to delete RETURNS clscrsretSUCC on success clscrsretBADARG if reslist or name is null clscrsretNORES if the resource is not in reslist */ clscrsret clscrs_reslist_delete_res(clscrs_reslist *reslist, const oratext *name); /* NAME clscrs_reslist_destroy DESCRIPTION Free the memory for a resource list. PARAMETERS reslist [in] - resource list for which the memory is to be freed RETURNS clscrsretSUCC on success */ clscrsret clscrs_reslist_destroy(clscrs_reslist **reslist); /* NAME clscrs_get_error_message DESCRIPTION Retrieve the error message corresponding to the return codes from a clscrs api. The memory for the error message is allocated by the caller. If the buffer is not large enough, the length is returned in msg_len. PARAMETERS ctx [in] - clscrs context err_code [in] - error code returned from the clscrs api msg [out] - message corresponding to err_code msg_len [inout] - length of the message buffer. RETURNS clscrsretSUCC on success */ clscrsret clscrs_get_error_message(clscrs_ctx *ctx, clscrsret err_code, oratext *msg, sb4 msg_len); /*--------------------------------------------------------------------------- INTERNAL FUNCTIONS ---------------------------------------------------------------------------*/ /* NAME clscrs_get_fixed_attrlist DESCRIPTION Get the list of attributes corresponding to an attribute group identifier. PARAMETERS ctx [in] - clscrs context attrgrp [in] - attribute group that identifies a group of attributes attrlist [out] - list of attributes returned that corresponds to attrgrp RETURNS clscrsretSUCC on success */ clscrs_splist* clscrs_get_fixed_attrlist(clscrs_ctx *ctx, clscrs_attr_grp attrgrp); /*--------------------------------------------------------------------------- INTERNAL FUNCTIONS ---------------------------------------------------------------------------*/ #endif /* CLSCRSX_ORACLE */ #ifdef __cplusplus } #endif /* __cplusplus */