Skip Headers
Oracle® Clusterware Administration and Deployment Guide
11g Release 1 (11.1)

B28255-07
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

D High Availability Oracle Clusterware Command-Line Reference and C API

This appendix describes the Oracle Clusterware application program interface (API) command reference and includes the following topics:

Note:

The Oracle Clusterware API demo is not supported for Windows.

Using Oracle Clusterware Commands

This section explains how to use the Oracle Clusterware commands to manage applications and application resources under the Oracle Clusterware framework.

Application Profile Syntax

The examples in this appendix show the command syntaxes that you use in application profiles. Lines starting with a pound sign (#) are comment lines and are not processed as part of a profile. A backslash (\) at the end of a line indicates that the next line is a continuation of the previous line. See the section titled "Using the crs_profile Command to Create An Application Resource Profile" to see a profile example.

Security and Permissions

Oracle Clusterware uses security similar to Linux or UNIX systems, where permissions may be specified for the owner, nodes of a group, or holders of specific privileges. There may also be default permissions for other users. These permissions are read, write, and run on Windows systems, and rwx on Linux or UNIX systems. Default ownership and permissions are set when you create an application profile. Table D-1 shows the Oracle Clusterware commands and their owners and describes which commands require write permission and which commands require run permission.

Table D-1 Oracle Clusterware Command Owner and Permissions Matrix

Owner Read Write Permission Required Run/Execute Permission Required

User

crs_stat {any options}

crs_register {no arguments}

crs_register -u

crs_unregister

crs_start

crs_stop

crs_relocate

crs_stat {no arguments}

crs_stat -l -t -r

Group

crs_stat {any options}

crs_register {no arguments}

crs_register -u

crs_unregister

crs_start

crs_stop

crs_relocate

crs_stat {no arguments}

crs_stat -l -t -r

Other

crs_stat {any options}

crs_register {no arguments}

crs_register -u

crs_unregister

crs_start

crs_stop

crs_relocate

crs_stat {no arguments}

crs_stat -l -t -r


Note:

On platforms that do not have a group concept, the group permissions are NULL or not set.

Note:

Do not use the Oracle Clusterware commands prefixed with crs_ (except for crs_stat) on resources that have names beginning with the prefix ora unless either Oracle Support asks you to, or unless Oracle has certified you as described in https://metalink.oracle.com. Server Control (SRVCTL) is the correct utility to use on Oracle resources. You can create resources that depend on resources that Oracle has defined. You can also use the Oracle Clusterware commands to inspect the configuration and status.

Oracle Clusterware Commands

Table D-2 alphabetically lists the Oracle Clusterware commands that this appendix describes. Note that the -q option is available for all commands and enables the command to run in quiet mode. This means that no messages are displayed on the console.

Table D-2 Oracle Clusterware Commands Summary

Command Description

crs_getperm

Lists the permissions associated with a resource.

crs_profile

Creates, validates, deletes, and updates an Oracle Clusterware application profile

crs_register

Registers configuration information for an application with the OCR.

crs_relocate

Relocates an application profile to another node.

crs_setperm

Sets permissions associated with a resource.

crs_stat

Lists the status of an application profile.

crs_start

Starts applications that have been registered.

crs_stop

Stops an Oracle Clusterware application.

crs_unregister

Removes the configuration information for an application profile from the OCR.


Note:

On platforms that do not have a group concept, the group permissions are NULL or not set.

crs_getperm

Lists the permissions defined for the resource. If any user other than root needs access to a resource that was created by the root user, you need to explicitly give them access. However, resources registered by users other than root are owned by the registering user, and can see their own resources. The access definitions are similar to Unix.

See Also:

The crs_setperm command to modify the permissions associated with a resource

Syntax and Options for crs_getperm

Use the crs_getperm command with the following syntax:

crs_getperm resource_name [-u user|-g group] [-q]

To obtain the permissions associated with a resource, use the following syntax:

crs_getperm resource_name

Example of crs_getperm

To list the permissions associated with the postman application, use the following command:

crs_getperm postman

====================
Name: postman
owner:root:rwx,pgrp:oinstall:r-x,other::r--,user:oracle:r-x,
=====================

Table D-3 crs_getperm Options

Option Description

-g group

Obtains the permissions associated with the specified (operating system) group.

-q

Runs the command in quiet mode (no messages are displayed on the console).

resource_name

Obtains the permissions associated with a specific resource.

-u user

Obtains the permissions associated with the specified user.


crs_profile

Creates, validates, deletes, and updates an Oracle Clusterware application profile. It works on the user's copy of a profile.

You can also use crs_profile to generate a template script. The crs_profile command creates new application profiles and validates, updates, deletes, or lists existing profiles. An application profile assigns values to attributes that define how a resource should be managed or monitored in a cluster. For the root user, profiles are written to the CRS_home/crs/profile directory. For nonprivileged users, the profile is written to the CRS_home/crs/public directory. Values in the profile that are left blank are ignored and may be omitted if not required. Omitted profile variables that are required for a resource type can cause validation or registration to fail.

After you have created an application profile and registered the application with Oracle Clusterware using the crs_register command, you can use other Oracle Clusterware commands, such as crs_stat, crs_start, crs_stop, crs_relocate, and crs_unregister, on the application. You must register applications using the crs_register command before the other Oracle Clusterware commands are available to manage the application. The crs_profile command may have other options for defining user-defined attributes in a profile.

Syntax and Options for the crs_profile Command

Use the crs_profile command with the following syntax to create an application profile template:

crs_profile -create resource_name -t application [-a action_script] [-B
 executable_pathname] [-dir directory] [-d description] [-p placement_policy] [-h
 hosting_nodes] [-r required_resources] [-l optional_resources]  [-o option,[...]]
 [attribute_flag attribute_value] [...] [-f] [-q]

crs_profile -create resource_name -t application
          [-dir directory_path] [-a action_script] [-B binary_pathname]
          [-d description] [-h hosting_members] [-r required_resources]
          [-l optional_resources] [-p placement_policy]
          [-o as=auto_start,ci=check_interval,ft=failure_threshold,
          fi=failure_interval,ra=restart_attempts,fd=failover_delay,
          st=script_timeout,ap=active_placement,bt=rebalance,
          ut=uptime_threshold,rt=start_timeout,pt=stop_timeout] [-f] [-q]

To create an application profile from an application profile template you use crs_profile to create a template (a cap) file. This file is then read automatically by the crs_register command which reads the data from the cap file and puts it in the OCR. For example:

crs_profile -create resource_name -I template_file [-f] [-q]

To validate the application profile syntax of a profile, enter the following command:

crs_profile -validate resource_name [-q]

To list one or more application profiles:

crs_profile -print [resource_name [...]] [-q]

To create an application profile template from an existing application profile:

crs_profile -template resource_name [-O template_file] [-q]

To update an application profile:

crs_profile -update resource_name [option [...]] [-q]

To delete an application profile and its associated action program:

crs_profile -delete resource_name [-q]

Note:

The crs_profile -delete command deletes the resource profile file but does not delete the action script file.

Table D-4 Options for the crs_profile Command

Option Description

[attribute_flag attribute_value]

All crs_profile commands take the following format:

crs_profile attribute_flag attribute_value

This command sets the specified attribute (whose flag is specified by attribute_flag) to the given value (whose value is specified by attribute_value) in the profile that gets generated. For example, the following command sets the -validate attribute to the value resource_name:

crs_profile -validate resource_name

[-a action_script]

Specifies the action program for the application. An action program has start, stop, and check entry points that are called by Oracle Clusterware. You can specify either a full path name for the script file or its filename.

[-B executable_pathname]

Specifies the location of the application executable and causes the crs_profile command to generate an action program file that contains the application executable path name.

-create resource_name

Creates a resource profile for the indicated application according to the specified options. A resource_name is a string containing a combination of characters [a-z, A-Z, 0-9, '.','_']. The resource name may not start with a period (.). The maximum length for a resource name is 128 characters. Resource profiles are created in the directory that you specify.

[-d description]

Specifies the description of the application. Enclose the description in double quotation marks ("") if it contains white space. If you do not specify an application description, then Oracle Clusterware uses the application name.

[-dir directory]

Specifies the file location where the profile is located.

[-h hosting_nodes]

Specifies an ordered list of nodes, separated by white space, that can host the application. If there is more than one node, then the list must be enclosed in double quotation marks (""). If you specify the -p option with a placement policy of preferred or unavailable, then you must also specify the -h option.

[-l optional_resources]

Specifies an ordered list of optional resources, separated by white space. If there are multiple optional resources specified, then the list must be enclosed in double quotation marks ("").

[-o option[,...]]

Specifies a comma-delimited list of attribute option names and their values. To see the list of attribute option names, see Table D-5, "Options for the -o Flag" or run the crs_profile -help command.

[-p placement_policy]

Specifies the policy according to which Oracle Clusterware selects the node on which to start or restart the application. You can specify balanced, favored, or restricted as placement policies. All policies except for balanced require you to also specify the -h flag.

-q

Runs the command in quiet mode (no messages are displayed on the console).

[-r required_resources]

Specifies an ordered list of resources, separated by spaces, on which the application depends. These resources must be active on any node on which the application is running. If there are multiple required resources, then the list must be enclosed in double quotation marks (""). If you do not specify a required resources list, then Oracle Clusterware imposes no required dependencies upon the application resource.

-t application

Indicates an application or application resource type.

-validate

Validates the application profile syntax of a profile.


Table D-5 Options for the -o Flag

Option Description

ap=active_placement

When set to 1, it reevaluates the placement policy when a new cluster node becomes available. With placement policies of FAVORED and RESTRICTED,a highly available application relocates to a more highly favored cluster node. The default is 0.

as=auto_start

Indicates whether Oracle Clusterware automatically starts a resource after a cluster restart. Valid AUTO_START values are:

  • always—Restarts the resource when the node restarts regardless of the state of the resource when the node stopped.

  • restore—Restores the resource to the same state that it was in when the node went down. If the state of the resource was offline (STATE=OFFLINE, TARGET=OFFLINE) when the node went down, then the resource remains offline when the node comes back up. The resource is started only if it was online before the node went down.

  • never—Oracle Clusterware never restarts the resource regardless of the state of the resource when the node stopped.

Note: Oracle only supports lower-case values for always, restore, and never.

ci=check_interval

Sets the time (in seconds) at which the check entry point of the application's action program runs. The check interval is the maximum amount of time that an application can be unavailable to clients before Oracle Clusterware attempts to restart it. The default check interval is 60 seconds.

fd=failover_delay

Specifies the number of seconds that Oracle Clusterware waits before attempting to relocate the application resource. An application resource that was running on a cluster node that failed restarts immediately on that node if it becomes available again within the failover delay period.

If application resources are dependent on each other due to required resources defined in application profiles, then all interdependent application resources wait for the largest failover delay that you have defined for any of the resources. The default failover delay is 0 (zero) seconds.

fi=failure_interval

Specify the time (in seconds) during which the failure threshold is calculated and applied. The default failure interval is 0 (zero). Oracle Clusterware uses a default failure interval of 0, which turns off monitoring of failure threshold and failure intervals. Specifying a nonzero failure interval has no effect unless the failure threshold is also nonzero.

ft=failure_threshold

Specifies the number of times that Oracle Clusterware may detect an application or application resource failure within the failure interval before it marks the application or application resource as unavailable and stops monitoring it. The value must be in the range 0-20. Setting the value to 0 (zero) turns off failure threshold monitoring. If you do not specify a failure threshold, then Oracle Clusterware uses a default failure threshold of 0 (zero).

ra=restart_attempts

Specifies the number of times that Oracle Clusterware attempts to restart the application or application resource on the current node before attempting to relocate it. The default number of restart attempts is 1.

st=script_timeout

Sets the maximum number of seconds within which an action program can run. The Oracle Clusterware commands and daemon return an error message and post an event to Event Manager (EVM) when they invoke action program entry points and the script does not complete its execution within this time. The default is 60 seconds.


Examples of the crs_profile Command

The following is an example of using the crs_profile command to create the application profile for the postman application:

crs_profile -create postman \
-t application \
-a postman.sh \
-o ci=5,ra=2"

The following is an example of using the crs_profile command to validate the application profile named dtcalc:

crs_profile -validate dtcalc

If you do not specify either the -a or -B options, then the profile is created without an action program value. You should create a readable, executable script and update the profile with this script's value before attempting to start the application. If you specify the -a option alone, then the action program specified must exist at the specified location or in the default directory if no path is specified. Otherwise, the command fails.

crs_register

The crs_register command registers one or more applications specified with the resource_name parameter for each application. This command requires write access to the target application. This command only succeeds if the profile is found either in the default location or in the directory specified by the -dir option. An application must be registered for Oracle Clusterware to monitor the resource or to start, restart, or relocate a highly available application associated with an application resource. An application registration must be updated for any changes to an application profile to take effect. Also, see the "Security and Permissions" section for information about the privileges required for this command.

An application can be registered or updated only if the CRS daemon is active and an Oracle Clusterware application profile exists in the profile directory for this application. If fields are missing from an application profile, then the profile is merged with the default profile template and Oracle uses the values in the default profile template.

The ownership and default permissions for the application are set during the registration process. You can register any .cap file as long as the permissions for the file permit read and write, for example, crs_profile and crs_register must be able to read the file. By default, the user who registers the application is the owner of the application. If the profile cannot be registered, then Oracle Clusterware displays messages explaining why. Use the crs_stat command to verify that the application is registered.

Syntax and Options for the crs_register Command

You can use the crs_register command to register and update applications. Use the following crs_register syntax to register an application:

crs_register resource_name [-dir directory_path] [...] [-u] [-f] [-q]

crs_register resource_name -update [-a action_script]
[-d description] [-h hosting_members] [-r required_resources]
[-l optional_resources] [-p placement_policy]
[-o as=auto_start,ci=check_interval,ft=failure_threshold,
fi=failure_interval,ra=restart_attempts,fd=failover_delay,
st=script_timeout,ap=active_placement,bt=rebalance,
ut=uptime_threshold,rt=start_timeout,pt=stop_timeout] [-q]

The resource_name [...] parameter can be the name of one or more application resources as specified in an application profile. If you do not specify any options, then the crs_relocate command relocates each specified application resource according to its placement policy and required resource lists. Oracle Clusterware does not relocate a resource if there are interdependent application resources unless you specify the -f option. A profile must exist for the application that you are registering.

Table D-6 Options on the crs_register Command

Option Description

[-dir directory_path]

Specifies the directory where the .cap file is located if the .cap file is not located in the default directory.

-f

Enables you to register a resource even though you have no execute permission on one or more required resources.

-u

Ensures the changes take effect immediately. Use crs_register -u immediately after issuing a crs_profile -update command or after manually editing an application profile.

[attribute_flag attribute_value]

All crs_profile commands take the following format:

crs_profile attribute_flag attribute_value

This command sets the specified attribute (whose flag is specified by attribute_flag) to the given value (whose value is specified by attribute_value) in the profile that gets generated. For example, the following command sets the -validate attribute to the value resource_name:

crs_profile -validate resource_name

[-a action_script]

Specifies the action program for the application. An action program has start, stop, and check entry points that are called by Oracle Clusterware. You can specify either a full path name for the script file or its filename.

[-d description]

Specifies the description of the application. Enclose the description in double quotation marks ("") if it contains white space. If you do not specify an application description, then Oracle Clusterware uses the application name.

[-h hosting_nodes]

Specifies an ordered list of nodes, separated by white space, that can host the application. If there is more than one node, then the list must be enclosed in double quotation marks (""). If you specify the -p option with a placement policy of preferred or unavailable, then you must also specify the -h option.

[-l optional_resources]

Specifies an ordered list of optional resources, separated by white space. If there are multiple optional resources specified, then the list must be enclosed in double quotation marks ("").

[-o option[,...]]

Specifies a comma-delimited list of attribute option names and their values. To see the list of attribute option names, see Table D-5, "Options for the -o Flag" or run the crs_profile -help command.

[-p placement_policy]

Specifies the policy according to which Oracle Clusterware selects the node on which to start or restart the application. You can specify balanced, favored, or restricted as placement policies. All policies except for balanced require you to also specify the -h flag.

-q

Runs the command in quiet mode (no messages are displayed on the console).

[-r required_resources]

Specifies an ordered list of resources, separated by spaces, on which the application depends. These resources must be active on any node on which the application is running. If there are multiple required resources, then the list must be enclosed in double quotation marks (""). If you do not specify a required resources list, then Oracle Clusterware imposes no required dependencies upon the application resource.


Use the following crs_register command syntax to update a registered application:

crs_register resource_name -update [option ...] [-o option,...] [-q]

See Also:

Table D-4 and Table D-5 for the listing of options and their definitions for using -update; the options for -update are the same as for the crs_profile command

Example of the crs_register Command

The following example registers an application named postman for which an application profile exists in the CRS_home/crs/profile directory:

CRS_home/bin/crs_register postman

Note:

The profile will be in the crs/profile directory if the profile is created by the root user. The profile will be in the crs/public directory if the profile is created by any other user.

Related Commands for the crs_register Command

crs_stat, crs_profile, crs_relocate, crs_start, crs_stop, crs_unregister

crs_relocate

The crs_relocate command relocates applications and application resources as specified by the command options that you use and the entries in your application profile. The specified application or application resource must be registered and running under Oracle Clusterware in the cluster environment before you can relocate it. The command displays a message if you specify a cluster node that is unavailable or if the attempt to relocate failed. Also, see the "Security and Permissions" section for information about the privileges required for this command.

When you issue a crs_relocate command, Oracle Clusterware first runs the stop entry point of the action program on the node on which it is currently running. Oracle Clusterware then performs the start entry point of the action program to start it on a new node.

If Oracle Clusterware fails to stop the application or application resource on the current node due to an action program error, then it marks it as UNKNOWN. You cannot issue the crs_relocate command on a resource in this state. Instead, run a crs_stop -f command on the resource and restart it by issuing he crs_start command to return it to the ONLINE state before you attempt to relocate it again. If Oracle Clusterware fails to restart an application resource, then you may need to check the resource action program.

If the action program start entry point fails to run successfully, then the stop entry point is run. If the stop entry point fails to run successfully, then the state is marked as UNKNOWN and relocation attempts are stopped. If the stop entry point succeeds, then the state is set to OFFLINE. The target state remains ONLINE however, so subsequent cluster node failures or restarts can cause Oracle Clusterware to attempt to restart the application. If you have not specified the node to which to relocate it and if there are available cluster nodes that satisfy the placement criteria, then Oracle Clusterware attempts to start the application on one of these available nodes.

If one or more user-defined attributes have been defined for application resources, then you can specify values for these attributes when relocating an application with the crs_relocate command. The specified value is passed to the action program as an environment variable with the attribute name.

The actions that Oracle Clusterware takes while relocating an application resource are echoed on the command line. You can also monitor them using the Event Manager (EVM). Standard error and standard output from a resource action program that is started by the crs_relocate command are redirected to the standard error and standard output for the crs_relocate command. Note that if the Oracle Clusterware daemon starts an application, then standard error and standard output of the action program is lost. In an action program, you can check for user invocation of the action program using reason codes.

Syntax and Options for the crs_relocate Command

Use the crs_relocate command with the following syntax:

crs_relocate resource_name [...] [-c cluster_node] [-f] [-q]

crs_relocate resource_name [-c cluster_node] [-q]

crs_relocate [USR_attribute_name=value] [...] resource_name [-c cluster_node] [-q]

crs_relocate -s source_node [-c cluster_node] [-q]

Table D-7 Options on the crs_relocate Command

Option Description

-c cluster_node

Relocates each indicated application or application resource to the specified node regardless of its placement policy. If required resources are not available on the destination node or if the application resource is restricted from that node, then the crs_relocate command fails and the application or application resource remains on the current node.

-f

Forces relocation of the specified applications, all applications dependent on them and all applications that they are dependent upon. This option is necessary for relocating any application that requires another application or one that is required by any ONLINE application.

-s source_node

Relocates all running applications or application resources from the source_node. If you do not also specify the -c option, then the crs_relocate command relocates each resource according to its placement policy and required resource lists.

-t

Lists information for all resources in a tabular form.

-q

Runs the command in quiet mode (no messages are displayed on the console).

[USR_attribute_name=value]

When starting the resource, this option sets the named attribute to the given value in the CRS resource's environment.


Example of the crs_relocate Command

The following example relocates an application resource to the node known as rac1:

crs_relocate postman -c rac1
Attempting to stop `postman` on node `rac2`
Stop of `postman` on node `rac1` succeeded
Attempting to start `postman` on node `rac1`
Start of `postman` on node `rac1` succeeded

The following example attempts to relocate all application resources from node rac2 to node rac1:

crs_relocate -s rac2 -c rac1
Attempting to stop `postman` on node `rac2`
Stop of `postman` on node `rac2` succeeded.
Attempting to start `postman` on node `rac1`
Start of `postman` on node `rac1` succeeded.
Attempting to stop `calc` on node `rac2`
Stop of `calc` on node `rac2` succeeded.
Attempting to start `calc` on node `rac1`
Start of `calc` on node `rac1` succeeded.

If a user-defined attribute USR_DEBUG has been defined, then the following example runs the stop and start entry point of the action program with the USR_DEBUG environment variable set to FALSE. This overrides any value set in the application profile. In the corresponding action program, if you add the following line to the appropriate section of the action program, then you can view the value:

echo $USR_DEBUG

Then issue the following command:

# crs_relocate USR_DEBUG=false database

crs_setperm

Modifies the permissions associated with a resource. This command is similar to the chmod command for Linux and UNIX systems or the Windows desktop options, in this order: File, Properties, Security, and Permissions.

See Also:

The crs_getperm command to obtain the permissions associated with a resource

Syntax and Options for the crs_setperm Command

Use the crs_setperm command with the following syntax:

crs_setperm resource_name -u aclstring [-q]

crs_setperm resource_name -x aclstring [-q]

crs_setperm resource_name -o user_name [-q]

crs_setperm resource_name -g group_name [-q]

Table D-8 Options on the crs_setperm Command

Option Description

-u

Updates the ACL string.

-x

Deletes the ACL string.

-o

Changes the owner of the resource.

Note: Only the root user can change the owner.

-g

Changes the primary group of the resource.

-q

Runs the command in quiet mode (no messages are displayed on the console).

aclstring

Is one of the following:


user:username:rwx
group:groupname:r-x
other::r--

Example of the crs_setperm Command

The following example modifies the permissions on the admin1 user for the postman application:

crs_setperm postman -u user:admin1:r-x

crs_stat

The crs_stat command provides status information for resources on the cluster nodes. To query resources with the crs_stat command, the CRS resource permissions must have read and execute permissions (r and x permissions on Linux and UNIX systems). An exception is the -g option, that anyone can use to verify whether a resource exists.

Resources are either ONLINE or OFFLINE as shown in the STATE attribute. An application resource in the ONLINE state is running successfully on a cluster node. This cluster node is shown indicating its state.

The TARGET value shows the state to which Oracle Clusterware attempts to set the resource. If the TARGET value is ONLINE and a cluster node fails, then Oracle Clusterware attempts to restart the application on another node if possible. If there is a condition forcing a resource STATE to be OFFLINE, such as a required resource that is OFFLINE, then the TARGET value remains ONLINE and Oracle Clusterware attempts to start the application or application resource once the condition is corrected.

A TARGET value for all non-application resources should be ONLINE unless the resource has a failure count higher than the failure threshold, in which case the TARGET is changed to OFFLINE. Oracle Clusterware then treats the resource as if its STATE were OFFLINE. If the STATE is ONLINE and the TARGET is OFFLINE, then you can reset the target value to ONLINE using the crs_start command.

The verbose status -v gives additional information that may be useful, especially for troubleshooting. The RESTART_COUNT value shows how many times an application resource has been restarted on a single cluster node. The maximum number of restarts before Oracle Clusterware stops restarting the application is equal to RESTART_ATTEMPTS. FAILURE_COUNT shows the number of times that a resource has failed within the FAILURE_INTERVAL defined in the application profile. The maximum number of failures before Oracle Clusterware stops attempting to restart an application is equal to the value set for the FAILURE_THRESHOLD parameter. If a cluster node fails and applications are waiting to be relocated due to the profile FAILOVER_DELAY attribute, then the verbose status also shows the FAILOVER_STATUS field. The FAILOVER_STATUS field is not shown at any other time. The FAILOVER_STATUS field shows the node the application failed on and how much time is left waiting for that node to restart before restarting on another node.

Syntax and Options for the crs_stat Command

Use the crs_stat command with the following syntax:

crs_stat [resource_name [...]] [-v] [-l] [-q] [-c cluster_node]

crs_stat [resource_name [...]] -t [-v] [-q] [-c cluster_node]

crs_stat -p [resource_name [...]] [-q]

crs_stat [-a] resource_name -g

crs_stat [-a] resource_name -r [-c cluster_node]

crs_stat -f [resource_name [...]] [-q] [-c cluster_node]

crs_stat -ls resource_name

To view information about all resources, enter the command with no arguments.

Table D-9 Options on the crs_stat Command

Option Description

-a resource_name

Used with the -g or -r option to verify whether the specified resource is registered or running under Oracle Clusterware. Specify the name of the resource as listed in its application profile.

-c cluster_node

Displays information about applications or application resources on the specified cluster node.

-f

Displays all information about the resource including extended information (-v) and the in-memory profile (-p).

-g

Returns 0 (zero) if the specified application or application resource is registered with Oracle Clusterware; returns 1 if it is not. This option only works if a single resource is specified with the -a option.

-l

Displays the status in a list (nontabular) format. This is the default format.

-ls

Lists resources, owners, and permissions for all resources.

-ls resource_name

Lists resources, owners, and permissions for a specified resource.

-p resource_name [...]]

Displays the status of the in-memory profile for the specified resources. If no resources are specified, then the status of the in-memory profile for all registered resources is displayed. If a resource is not registered, its status is not displayed.

-q

Runs the command in quiet mode (no messages are displayed on the console).

-r

Returns 0 (zero) if the specified application or application resource is running under Oracle Clusterware; returns 1 if it is not. This option can only be successful if a single resource is specified with the -a option.

-t

Lists information for all resources in a tabular form.

-v

Lists how many times a resource has been restarted or has failed within the resource failure interval, the maximum number of times that a resource can be restarted or can fail, and the target state of the application. Also, this option lists normal status information.

This option displays extended information about the status of resources. Extra attributes shown include RESTART_COUNT and FAILURE_COUNT. The RESTART_COUNT attribute shows the number of restarts of the application that have been attempted since it was started. The FAILURE_COUNT attribute shows how many failures have occurred during the last FAILURE_THRESHOLD in seconds. The attribute FAILOVER_STATUS shows the time at which an application resource started while waiting to relocate due to a cluster node failure if the resource has a FAILOVER_DELAY value greater than 0. It is not displayed otherwise.


Examples of the crs_stat Command

The following example displays the status information for the postman application:

crs_stat postman

NAME=postman
TYPE=application
TARGET=ONLINE
STATE=ONLINE on rac2

The following example displays the status information in a tabular form:

crs_stat -t

Name         Type        Target      State     Host
----------------------------------------------------------------
cluster_lockd application ONLINE    ONLINE     rac2
dhcp          application OFFLINE   OFFLINE

The following example shows the output for the crs_stat command with the -v option for the node rac2:

crs_stat -v

NAME=cluster_lockd
TYPE=application
RESTART_ATTEMPTS=30
RESTART_COUNT=0
FAILURE_THRESHOLD=0
FAILURE_COUNT=0
TARGET=ONLINE
STATE=ONLINE on rac2

crs_start

The crs_start command sets an application or application resource target state to ONLINE and attempts to start specified registered applications or application resources. The target state is the state that Oracle Clusterware attempts to achieve. Also, see the "Security and Permissions" section for information about the privileges required for this command.

There are several user-defined attributes available for starting an application with crs_start. The specified value is passed to the action program as an environment variable with the attribute name.

If you do not specify one node on which to start the application and there are available cluster nodes that satisfy the placement criteria, then Oracle Clusterware attempts to start the application on one of the available nodes. You must stop a resource that has failed before restarting it. You should also confirm why your action program is failing.

The crs_start command starts dependent resources as defined in the application profile REQUIRED_RESOURCE fields. After a registered resource is started, you must use the crs_stop command to end its execution.

The crs_start command displays status messages and if there are problems starting an application, then feedback is displayed. Standard error and standard output from a resource action program invoked by the crs_start command are redirected to the standard error and standard output for crs_start. Note that if the CRS daemon starts an application, then standard error and standard output of the action program is lost. Within an action program, you can check for user invocation of the action program using reason codes.

Syntax and Options for the crs_start Command

Use the crs_start command with the following syntax:

crs_start resource_name  [...] [-c cluster_node] [-q] [-f]

crs_start -all [-q]

crs_start [USR_attribute_name=value] [...] resource_name [-c node_name] [-q]

For resource_name [...], the names are as specified in an application profile of one or more resources to be started. The resource must be registered with Oracle Clusterware.

Table D-10 Options On the crs_start Command

Option Description

-all

Starts all registered Oracle Clusterware applications or application resources on active cluster nodes, according to their placement policies and required resource lists.

-c node_name

Starts each indicated resource on the specified node if the cluster node is enabled by the placement policy and resource dependencies. If the cluster node specified is not enabled by the placement policy and resource dependencies, then the crs_start command fails. If the specified node is not available, the command fails. If one of the specified resources fails to start, then the command still attempts to start other resources listed on the command line.

-f

Forces starting of a specified application or application resource if all of the required resources are available or can be started. Any applications or application resources in the specified application profile's required resource list are started if not currently running or are relocated if they are running on another cluster node. Use this option with only one specified application resource at a time.

-q

Runs the command in quiet mode (no messages are displayed on the console).

[USR_attribute_name=value]

 

Examples of the crs_start Command

The following example starts an application named postman:

crs_start postman
Attempting to start `postman` on node `rac1`
Start of `postman` on node `rac1` succeeded.

The following example starts the application on a specific cluster node rac2:

crs_start -c rac2 postman
Attempting to start `postman` on node `rac2`
Start of `postman` on node `rac2` succeeded.

crs_stop

Stops an application on the specified node. You can run the crs_stat command to verify that the application you specify is stopped.

Syntax and Options for the crs_stop Command

Use the crs_stop command with the following syntax:

crs_stop resource_name [...] [-f] [-q]

crs_stop -c cluster_node [...] [-q]

crs_stop -all [-q]

crs_stop [USR_attribute_name=value] [...] resource_name [-q]

-c cluster_node [...]

Specifies one or more active cluster nodes on which to stop all of the applications or application resources. You can use the options described in Table D-11:

Table D-11 Options on the crs_stop Command

Option Description

-all

Stops all registered Oracle Clusterware applications or application resources on active cluster nodes.

-c cluster_node

Stops applications or application resources on the specified cluster node.

-f

Forces termination of the indicated applications or application resources and all application resources dependent on the specified resources. This option is useful to stop all application resources when the crs_stop command fails because of application resources that are dependent on the specified resource or if the application is in the UNKNOWN state because of an unsuccessful stop. This option makes the crs_stop command ignore any errors that are reported by an action program.

-q

Runs the command in quiet mode (no messages are displayed on the console).


Examples of the crs_stop Command

To stop an application named dtcalc, enter the following command:

crs_stop dtcalc

Status Messages for the crs_stop Command

Oracle Clusterware displays the following status messages:

Attempting to stop `dtcalc` on node `rac2`
Stop of `dtcalc` on node `rac2` succeeded.

crs_unregister

The crs_unregister command removes the registration information of Oracle Clusterware resources from the binary Oracle Clusterware registry database. Oracle Clusterware will no longer acknowledge this resource. An application associated with a resource that is unregistered is no longer highly available. Also, see the "Security and Permissions" section for information about the privileges required for this command.

Upon successful completion of the crs_unregister command, the resource is removed from the online Oracle Clusterware environment. You cannot unregister a resource that is a required resource for another resource. You must stop the resource by using the crs_stop command before unregistering it.

Syntax and Options for the crs_unregister Command

Use the crs_unregister command with the following syntax:

crs_unregister resource_name [...] [-q]

The -q option runs the command in quiet mode (no messages are displayed on the console).

Example of the crs_unregister Command

The following example unregisters a highly available application called postman:

crs_unregister postman

C Application Programming Interface to Oracle Clusterware

The APIs described in this section provide access to operational control of resources that Oracle Clusterware manages. The API is used to register user applications to the Oracle Clusterware system so that they can be managed by Oracle Clusterware and made highly available. When 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 Oracle Clusterware. The Oracle Clusterware services are provided by another process, such as the CRSD process, running outside the database server. These APIs communicate with the CRSD process using an IPC mechanism.

Note:

You can install the Oracle Clusterware high availability Application Programming Interface (API) from the Oracle Database client installation media.

clscrs_init_crs

Initializes a context for communications with Oracle Clusterware.

Parameters

  • ctx—Context to initialize, caller allocated storage

  • errf—A Callback function for the error info, or NULL

  • errCtx—Context for the error callback func, or NULL

  • flagsCLSCRS_FLAG_TRACE, to enable tracing of lower layers

  • CLSCRS_FLAG_USETHREADS—Enables using the clscrs context in multiple threads

Returns

Status enum.

Syntax

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

clscrs_term_crs

Releases a context for communications with Oracle Clusterware.

Parameter

ctx—Context previously initialized with clscrs_init_crs.

Returns

status enum

Syntax

CLSCRS_STAT clscrs_term_crs( clscrs_ctx **ctx);

clscrs_getnodename

Returns the correct node name. If you issue this command within a configured cluster, then this is the name as known to the clusterware. If not in a cluster, then the name is as known through other clusterware means. Getting a node name may require a lot of resources in the first call, especially if CLSCRS was not initialized with a preexisting CSS context.

Parameters

  • ctx—Context previously initialized with clscrs_init

  • node_name—Filled in node name

Syntax

CLSCRS_STAT clscrs_getnodename(clscrs_ctx *ctx, oratext *node_name);

clscrs_env_create

Creates a call environment describing the parameters to the Oracle Clusterware calls. The memory is owned by clscrs which is released by a call to clscrs_env_delete.

Parameters

  • context—Input context

  • env—Output environment pointer

Returns

status enum

Syntax

CLSCRS_STAT clscrs_env_create( clscrs_ctx *ctx, clscrs_env *env );

clscrs_env_set

Sets an attribute or value argument in an environment for the Oracle Clusterware calls; the value may be NULL.

Parameters

  • env—Previously created environment

  • attr—Attribute name

  • val—Attribute value, may be NULL pointer

Returns

environment status enum

Syntax

CLSCRS_ENVCODE clscrs_env_set(clscrs_env env, const  oratext *attr, const oratext *val);

clscrs_env_delete

Deletes an environment for the Oracle Clusterware calls. The environment must be created again before use. You cannot delete an environment and then set new parameters.

Parameters

  • env—The environment whose contents are deleted

Returns

environment status enum.

Syntax

CLSCRS_ENVCODE clscrs_env_delete(clscrs_env env);

clscrs_env_format

Creates a callback with formatted environment lines.

Parameters

  • env—Env to dump

  • msgf—Callback function

  • msgp—Argument to msgp, uninterpreted

Returns

None.

Syntax

void clscrs_env_format( clscrs_env env, clscrs_msgf msgf, void *msgp );

clscrs_start_resource

Direct Oracle Clusterware to start a named set of resources. If a host is specified, then start there, otherwise start according to the placement policy for the resources in question. If the flag is async, then msgf is never called and Oracle returns the OK status after initiating the call to Oracle Clusterware, and the actual starts are performed asynchronously, and msgf will never be called. If flag is not async and msgf is not NULL, then msgf will be driven one line at a time with collected output from the start programs.

Parameters

  • ctx—The context

  • names—The resource(s) to start

  • num_names—The number of resources in names[] to start

  • host—The host name on which to start the resource, may be NULL

  • env—Environment arguments to start

  • msgf—User message callback, may be NULL

  • msgp—User callback argument, may be NULL

  • msgf—Callback function

  • msgf—Callback function

Returns

status enum

Syntax

CLSCRS_STAT clscrs_start_resource( clscrs_ctx *ctx, const oratext *name[], sword
 num_names, const oratext *host, clscrs_env env, clscrs_msgf msgf, void *msgp,
 uword flag );

clscrs_stop_resource

Directs Oracle Clusterware to stop a named set of resources. The flag enables async stop.

Parameters

  • ctx— the context

  • names—The resource(s) to stop

  • num_names—Number of resources in names[] to stop

  • flag—Async, force options

Returns

status enum

Syntax

clscrs_stop_resource( clscrs_ctx *ctx, const oratext *names[], sword num_names,
clscrs_env env, clscrs_msgf msgf, void *msgarg, uword flag );

clscrs_check_resource

Direct Oracle Clusterware to run the check actions for the identified resources. A delay can be specified to indicate a time to wait in seconds before the check action is performed on the server. This occurs after the call returns. This can be used to let something run before performing the check. For each resource identified by the in_splist, 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 of the 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

  • in_splist [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 check operation for each resource

Returns

status enum.

Syntax

clscrs_check_resource( clscrs_splist *in_splist, ub4 delay_seconds, uword flags,
 clscrs_reslist *op_status);

clscrs_register_resource

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, you must create and destroy it 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 process

Syntax

clscrs_register_resource(clscrs_reslist *in_reslist, uword flags, clscrs_reslist *op_status);

clscrs_unregister_resource

Unregisters 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. You must create and destroy it 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 process

Syntax

clscrs_unregister_resource(clscrs_splist *rqlist, uword flags, clscrs_reslist *op_status);

clscrs_stat

Obtains 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 node name 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 no values for this parameter. 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 predefined 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_attrs [in]—List to specify the attributes to be returned for each resource

  • res_flags [in]—Flags to restrict the resources being matched

  • out_reslist [out]—List holding the returned resource information

Returns

  • CLSCRS_STAT_SUCCESS if information is obtained 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 process

Syntax

clscrs_stat(clscrs_splist *rqlist, oratext *nodename, uword res_flags, clscrs_
splist *res_attrs, clscrs_reslist *out_reslist);

Functions for Managing Resource Structures

This section describes functions for creating, managing, and destroying resources and the attributes associated with resources. The following structures are used in this section:

Export Operations

This section describes the following export operations:

Stringpair Operations

This section describes the stringpair operations.

clscrs_sp_set

Changes 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 for which you want to set a value

  • value [in]—Value component of the stringpair (may be NULL)

Returns

  • clscrsretSUCC on success

  • clscrsretBADARG if the sp argument is NULL

Syntax

clscrsret clscrs_sp_set(clscrs_sp *sp, const oratext *value);
clscrs_sp_get

Gets the name and value components of a stringpair.

Parameters

  • sp [in]—Stringpair for which the name and value are being obtained

  • 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

Syntax

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

Gets the value component of a stringpair.

Parameters

  • sp [in]—Stringpair for which the name and value are being obtained

  • value [out]—Value component of the stringpair (may be NULL)

Returns

  • clscrsretSUCC on success

  • clscrsretBADARG if the sp argument is NULL

Syntax

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

Splist Operations

This section describes the splist operations.

clscrs_splist_create

Creates 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

Syntax

clscrsret clscrs_splist_create(clscrs_ctx *ctx, clscrs_splist **splist);
clscrs_splist_create_and_set

Creates 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

Syntax

clscrsret clscrs_splist_create_and_set(clscrs_ctx *ctx, const oratext 
*name, const oratext *value, clscrs_splist **splist);
clscrs_splist_append

Adds 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

Syntax

clscrsret clscrs_splist_append(clscrs_splist *splist, const oratext *name, const oratext *value);
clscrs_splist_first

Gets the first stringpair (sp) from a stringpair list (splist).

Parameters

  • name [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

Syntax

clscrsret clscrs_splist_first(clscrs_splist *splist, clscrs_sp **sp);
clscrs_splist_next

Gets the current next stringpair (sp) from a stringpair list (splist). This function is called to iterate over the stringpairs in a splist.

Parameters

  • name [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

Syntax

clscrsret clscrs_splist_next(clscrs_splist *splist, clscrs_sp **sp);
clscrs_splist_replace

Replaces 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 successclscrsretBADARG if the name argument is NULL

  • clscrsretBADARG if the name argument is NULL

  • clscrsretBADARG if the name argument is NULL

Syntax

clscrsret clscrs_splist_replace(clscrs_splist *splist, const oratext *name, const oratext *value);
clscrs_splist_delete_sp

Deletes a stringpair (sp) from a stringpair list (splist).

Parameters

  • splist [in]Splist from which to delete the {name, value} stringpair.

  • splist [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

Syntax

clscrsret clscrs_splist_delete_sp(clscrs_splist *splist, const oratext *name);
clscrs_splist_find

Finds 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

Syntax

clscrsret clscrs_splist_find(clscrs_splist *splist, const oratext *name, oratext **value);
clscrs_splist_count

Counts 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

Syntax

clscrsret clscrs_splist_count(clscrs_splist *splist, ub4 *count);
clscrs_splist_destroy

Frees the memory for a stringpair list (splist).

Parameter

  • splist [in]Splist to destroy

Returns

  • clscrsretSUCC on success

Syntax

clscrsret clscrs_splist_destroy(clscrs_splist **splist);
clscrs_res_create

Creates 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

Syntax

clscrsret clscrs_res_create(clscrs_ctx *ctx, const oratext *resname, clscrs_res **res);
clscrs_res_get_name

Gets the name of a resource.

Parameters

  • res [in]—Resource for which the name is obtained

  • name [out]—Name of the resource

Returns

  • clscrsretSUCC on success

  • clscrsretBADARG if the resource argument is NULL

Syntax

clscrsret clscrs_res_get_name(clscrs_res *res, oratext **name);
clscrs_res_set_attr

Sets a resource attribute for a resource.

Paramters

  • 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

Syntax

clscrsret clscrs_res_set_attr(clscrs_res *res, const oratext *attrname, const oratext *value);
clscrs_res_get_attr

Gets a resource attribute for a resource.

Parameters

  • res [in]—Resource for which the attribute is obtained

  • 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

Syntax

clscrsret clscrs_res_get_attr(clscrs_res *res, const oratext *attrname, oratext **value);
clscrs_res_get_attr_list

Gets the attribute list for a resource. The attribute list is a list of stringpairs. The client does not allocate the memory for attribute list.

Paramters

  • res [in]—Resource for which the attribute list

  • 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

Syntax

clscrsret clscrs_res_get_attr_list(clscrs_res *res, clscrs_splist **attrlist);
clscrs_res_set_attr_list

Sets 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

Syntax

clscrsret clscrs_res_set_attr_list(clscrs_res *res, clscrs_splist *attrlist);
clscrs_res_attr_count

Gets the number of attributes for a resource.

Parameters

  • res [in]—Resource for which number of attributes is obtained

  • count [out]—Number of attributes for the given resource

Returns

  • clscrsretSUCC on success

  • clscrsretBADARG if the resource is NULL

Syntax

clscrsret clscrs_res_attr_count(clscrs_res *res, ub4 *count);
clscrs_res_get_op_status

Gets 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 obtained

  • 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

Syntax

clscrsret clscrs_res_get_op_status(clscrs_res *res, CLSCRS_STAT *status, oratext **msg);
clscrs_res_get_registered

Gets 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

Syntax

clscrsret clscrs_res_get_registered(clscrs_res *res, boolean *registered);
clscrs_res_get_node_list

Gets 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 obtained

  • nodelist [out]Splist holding the node(s)

Returns

  • clscrsretSUCC on success

  • clscrsretBADARG if the resource is NULL

Syntax

clscrsret clscrs_res_get_node_list(clscrs_res *res, clscrs_splist **nodelist);
clscrs_res_destroy

Frees the memory for a resource.

Parameter

  • res [in]—Resource for which the memory is freed

Returns

  • clscrsretSUCC on success

Syntax

clscrsret clscrs_res_destroy(clscrs_res **res);
clscrs_reslist_create

Creates 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

Syntax

clscrsret clscrs_reslist_create(clscrs_ctx *ctx, clscrs_reslist **reslist);
clscrs_reslist_append

Adds 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

Syntax

clscrsret clscrs_reslist_append(clscrs_reslist *reslist, clscrs_res *res);
clscrs_reslist_first

Gets the first resource on a resource list.

Parameters

  • reslist [in]—Resource list for which the first resource is obtained

  • 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

Syntax

clscrsret clscrs_reslist_first(clscrs_reslist *reslist, clscrs_res **res);
clscrs_reslist_next

Gets 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 obtained

  • 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

Syntax

clscrsret clscrs_reslist_next(clscrs_reslist *reslist, clscrs_res **res);
clscrs_reslist_find

Finds a resource in a resource list.

Parameters

  • reslist [in]—Resource list (empty) that is created

  • name [in]—Name of the resource that is being obtained

  • 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

Syntax

clscrsret clscrs_reslist_find(clscrs_reslist *reslist, const oratext *name, clscrs_res **res);
clscrs_reslist_count

Counts the number of resources in a resource list.

Parameters

  • reslist [in]—Resource list for which the count is obtained

  • count [out]—Number of resources in the resource list

Returns

  • clscrsretSUCC on success

  • clscrsretBADARG if reslist is NULL

Syntax

clscrsret clscrs_reslist_count(clscrs_reslist *reslist, ub4 *count);
clscrs_reslist_delete_res

Deletes 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

Syntax

clscrsret clscrs_reslist_delete_res(clscrs_reslist *reslist, 
clscrs_reslist_destroy

Frees the memory for a resource list.

Parameters

  • reslist [in]—Resource list for which the memory is to be freed

Returns

  • clscrsretSUCC on success

Syntax

clscrsret clscrs_reslist_destroy(clscrs_reslist **reslist);
clscrs_get_error_message

Retrieves 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

Syntax

clscrsret clscrs_get_error_message(clscrs_ctx *ctx, clscrsret err_code, oratext *msg, sb4 msg_len);
clscrs_get_fixed_attrlist

Gets 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 the attribute group

Returns

  • clscrsretSUCC on success

Syntax

clscrs_splist* clscrs_get_fixed_attrlist(clscrs_ctx *ctx, clscrs_attr_grp attrgrp);

Resource Operations

This section describes resource functions. The clscrs_res resource abstraction contains the name of a resource and additional data appropriate to the context in which it is used. Sometimes it carries status and error return information about an operation. Other times it contains attribute data as input to an operation. A resource may be in exactly one resource list. If so, its successor may be found with the NEXT operation.

CLSCRSRET clscrs_res_create(clscrs_cts *ctx, const oratext *resname, clscrs_res **res)

Creates a single resource and fills in a handle to it. The resname must be provided, and cannot be NULL.

CLSCRSRET clscrs_res_get_name (clscrs_res *res, oratext **name);

Returns a pointer to the name of a resource. The returned name pointer is only valid as long as the resource exists.

CLSCRSRET clscrs_res_get_op_status (clscrs_res *res, CLSCRS_STAT *stat, oratext **msg)

If there is a valid operation error value in the resource, fills in the stat and the pointer to an error message and returns SUCCESS. May fill in a NULL for the msg. If there is no valid operation status, returns INVALID.

clscrs_splist *clscrs_res_get_node_list(clscrs_res *res);

Returns an splist holding the nodes currently hosting the resource, or NULL if there is no host for the resource or there are no attributes. The count of the list may obtained and the list iterated. The list is owned by the resource and will be destroyed when the resource is destroyed. This operation is a special case, interpreting the semantics of the attribute or attributes that may hold the current hosting member list. There is no specified ordering of the list.

CLSCRSRET clscrs_res_get_attr(clscrs_res *res, const oratext *attrname, oratext **value);

Fills in a pointer to the value of the attribute with the given name and returns SUCCESS if found, or FAILURE if the name is not present in the attribute set of the resource, and INVALID if there is no attribute list in the resource. May assert if given an invalid resource handle.

CLSCRSRET clscrs_res_set_attr(clscrs_res *res, oratext *attrname, oratext *value);

Sets the value of the attribute with the given name and returns SUCCESS or FAILURE if the name is not present in the attribute set of the resource. If the attribute already exists, then its current value will be replaced. On return, the memory for the name and value may be recycled.

CLSCRSRET clscrs_res_attr_count(clscrs_res *res, ub4 *count);

Fills in the number of attributes that will be returned with a scan using an attrIter. Returns SUCCESS if there are attributes. If there are no attributes, returns INVALID, but still sets the count to zero.

CLSCRSRET clscrs_res_get_attr_list(clscrs_res *res, clscrs_splist **attrlist);

Returns an splist for the attributes of the resource, allowing next() operations for a scan. The list is owned by the resource, which will destroy it when the resource is destroyed. Returns SUCCESS if there is an attribute list, or INVALID if there is not one in the resource. There is no specified ordering of the list.

Resource List Operations

This section describes the resource list operations. The clscrs_reslist resource list is an abstraction that contains information about zero or more resources. A list is created, appended, iterated over, and destroyed.

CLSCRSRET clscrs_reslist_create(clscrs_ctx *ctx, clscrs_reslist **reslist)

Creates a resource list and fills a handle.

CLSCRSRET clscrs_reslist_count(clscrs_reslist *reslist, ub4 *count)

Fills a count of the number of resources in a list.

CLSCRSRET clscrs_reslist_first(clscrs_reslist *reslist, clscrs_res **first)

Fills a handle to the first resource in the list of resources. If the list is empty, fill in NULL.

CLSCRSRET clscrs_reslist_next(clscrs_reslist *reslist, clscrs_res **next)

Fills a handle to the next resource in the list of resources. If the list is empty, fill in NULL.

CLSCRSRET clscrs_reslist_find(clscrs_reslist *reslist, const oratext *name, clscrs_res **res)

Finds a resource by name in a reslist, and fill in a handle to the one located. If the resource is not found, fill in NULL. Does an exact match lookup with no pattern matching.

CLSCRS_RES *clscrs_reslist_destroy(clscrs_res *res)

Deletes a resource list and all of the resources that it currently contains.