5
The Command-Line Interface

Oracle Real Application Clusters Guard provides a command-line interface as an alternative to using Oracle Real Application Clusters Guard Manager for managing resources in a cluster. For example, using the ORACGCMD command at the command prompt, you can take Oracle resources offline or bring them online. The ORACGCMD command is useful if you want to manage Oracle resources from batch programs or scripts.

---

ORACGCMD

The ORACGCMD command allows you to perform many of the same operations that you can perform with Oracle Real Application Clusters Guard Manager. To run the ORACGCMD command, specify the full path, beginning with the location where Oracle Real Application Clusters Guard Manager is installed:

<Oracle_Home>\fs\fsmgr\bin\oracgcmd.exe

If you do not use this path, the Windows operating system will not be able to locate the ORACGCMD command.

Note: Because of possible conflicts with other Oracle products installed on your system, do not include the directory <Oracle_Home>\fs\fsmgr\bin in your system path environment variable.

Format

To use the ORACGCMD command, open a command prompt window and type the ORACGCMD command line using the following syntax:

ORACGCMD <action> <name> /CLUSTER=cluster_name [<qualifier>]

Note: For clarity, the full path for ORACGCMD is omitted from the syntax and examples in this chapter.

Description

Oracle Real Application Clusters Guard supplies the ORACGCMD command, which you can use in scripts to do many of the same functions that you can do with Oracle Real Application Clusters Guard Manager. For example, you can use the ORACGCMD command to take cluster resources offline before you perform nightly backups, and then place the resources online again when the backups are complete.

You can execute the ORACGCMD command on any system where Oracle Real Application Clusters Guard Manager is installed. (The ORACGCMD software is a component of Oracle Real Application Clusters Guard Manager.)

When you execute certain ORACGCMD commands, you can specify the name of a log file to capture the results of the operation. The following table notes which commands can be logged.

Command Parameters

action

Specifies the action that you want applied to the group, resource, or cluster. Use one of the actions described in the following table:

Action	Description
DISABLEISALIVE	Disables Is Alive and Looks Alive polling for the named database instance until one of the following occurs: You explicitly enable Is Alive polling with the ORACGCMD ENABLEISALIVE command. The instance is placed online. The Verify Group command will issue a warning if it finds that Is Alive polling is disabled for an instance, but it will not reenable Is Alive polling.
DUMPCLUSTER	Prints cluster configuration information. Output from this operation is written to the file name that you specify with the /LOGFILE qualifier.
ENABLEISALIVE	Enables Is Alive and Looks Alive polling for the named database instance if they were disabled with the ORACGCMD DISABLEISALIVE command.
MOVEGROUP	Moves the group of resources to the node that you specify with the /NODE command qualifier. Output from this operation is written to the file name that you specify with the /LOGFILE qualifier.
MOVEPRIMARY	Takes the Oracle Real Application Clusters database instance that holds the primary role offline. This results in a role failover, whereby the instance that had the secondary role now holds the primary role. Only valid for Oracle Real Application Clusters databases deployed in a primary/secondary configuration.
OFFLINEGROUP	Takes the group offline.
OFFLINEORAC	Takes all instances of the named Oracle Real Application Clusters database offline.
OFFLINERESOURCE	Takes the resource offline. For Oracle database instance resources, this operation requires the /OFFLINE command qualifier.
ONLINEGROUP	Places the group online.
ONLINEORAC	Places all instances of the named Oracle Real Application Clusters database online.
ONLINERESOURCE	Places the resource online.
RESTORE	Brings the secondary instance online. (If both instances are offline, this returns an error message indicating that the instance with the primary role is not online.) Only valid for Oracle Real Application Clusters databases deployed in a primary/secondary configuration.
STOPSECONDARY	Stops the Oracle Real Application Clusters database instance that currently holds the secondary role. Only valid for Oracle Real Application Clusters databases deployed in a primary/secondary configuration.
SWITCHOVER	Reverses instance roles. The instance with the primary role assumes the secondary role and instance with the secondary role assumes the primary role. Issuing this is equivalent to issuing the MOVEPRIMARY command followed by the RESTORE command. Only valid for Oracle Real Application Clusters databases deployed in a primary/secondary configuration.
VERIFYALLGROUPS	Verifies all groups configured by Oracle Real Application Clusters Guard on the given cluster. Output from this operation is written to the file name that you specify with the /LOGFILE qualifier.
VERIFYCLUSTER	Verifies the cluster configuration. Output from this operation is written to the file name that you specify with the /LOGFILE qualifier.
VERIFYGROUP	Verifies a single group configured by Oracle Real Application Clusters Guard. Output from this operation is written to the file name that you specify with the /LOGFILE qualifier.
VERIFYORAC	Verifies the named Oracle Real Application Clusters database that has been configured into the MSCS cluster. Output from this operation is written to the file name that you specify with the /LOGFILE qualifier.

The action parameter must be the first argument to the ORACGCMD command.

name

The name of the resource, group, or Oracle Real Application Clusters database on which you want the ORACGCMD command to take action. For example, Sales1 is a valid name for a database instance resource.

This parameter must follow the action parameter. The name parameter is required for all ORACGCMD command actions except for the DUMPCLUSTER, VERIFYALLGROUPS, and VERIFYCLUSTER actions.

Command Qualifiers

/CLUSTER=cluster-name

Specifies the name of the cluster on which the ORACGCMD command will execute.

This qualifier is required.

/LOGFILE=file-name

Specifies the location of the log file that a long-running operation creates when the DUMPCLUSTER, MOVEGROUP, VERIFYCLUSTER, VERIFYGROUP, VERIFYALLGROUPS, or VERIFYORAC, action is performed. If you do not specify the LOGFILE qualifier, the log file is written to the current output device, which is typically the system console.

This qualifier is optional.

NODE=destination-node-name

Specifies the name of the node to which you want a group to be moved. Use this qualifier only when you specify the MOVEGROUP action.

/OFFLINE=offline-option

Use this qualifier only when you specify the OFFLINERESOURCE or OFFLINEORAC action to take an Oracle Real Application Clusters database instance offline or an entire Oracle Real Application Clusters database offline (respectively). If you do not supply one of the offline-option modes from the following table, the database instance or instances will be taken offline in the immediate mode (the default):

Mode	Description
Abort	Shuts down a database instance or instances instantaneously. If possible, use the abort mode of shutdown only in the following situations: The database instance or one of its applications is functioning irregularly and neither the immediate nor the normal mode of shutdown works. You need to shut down the database instance instantaneously (for example, you know a power shutdown is going to occur in one minute). Database recovery procedures are performed when the database is restarted.
Immediate	Shuts down a database instance or instances immediately by terminating SQL statements in progress, rolling back uncommitted transactions, and disconnecting users. The immediate mode is the default mode to take an instance offline. If possible, choose the immediate mode only in the following situations: A power shutdown is going to occur soon. The database instance or one of its applications is functioning irregularly. You are preparing to perform a database backup operation.
Normal	Shuts down a database instance or instances by: Disallowing new connections to the instance or instances after the command is issued Waiting for all connected users to disconnect before actually shutting down the database instance or instances
Transactional	Shuts down the database instance or instances only after all of the current transactions have completed.

/DOMAIN=domain-name

Specifies the domain to which the user account (specified with the /USER qualifier) is located.

This qualifier is optional on all clients except Windows 2000 clients; however, if you enter a domain name, you must also enter a user name and a password.

/PWD=password

Specifies the password for the account that is specified with the /USER qualifier.

This qualifier is optional on all clients except Windows 2000 clients; however, if you enter a password, you must also enter a user name and a domain name.

/USER=username

Specifies the user name for a domain account that has Administrator privileges on all cluster nodes.

This qualifier is optional on all clients except Windows 2000 clients; however, if you enter a user name, you must also enter a password and a domain name.

Usage Notes

• The action parameter must be the first argument to the ORACGCMD command.

• The domain, user name, and password qualifiers supply the account information to connect to Oracle Real Application Clusters Guard Server. You cannot enter one of these qualifiers without entering the other two, or a syntax error will occur. If the account information is not supplied, the user logged on when the ORACGCMD command is invoked will be authenticated by the server. If the current account does not have the required privileges to perform operations in an Oracle Real Application Clusters Guard environment, an error message will be generated.

• The parser accepts either a slash (/) or a hyphen (-) as the delimiter between command qualifiers.

• The command parameters and qualifiers are not case-sensitive; you can use either uppercase or lowercase letters, or a combination of both cases.

• A group or resource name that contains one or more spaces must be within quotation marks; for example, "Sales Group."

• You must enter a space between qualifiers in the command line. The following examples show correct and incorrect spacing in the command line:

  Correct usage:

  ORACGCMD onlineorac sales /CLUSTER=ntclu-150 /USER=smith /PWD=smithpwd  
  /DOMAIN=newengland
  
  

  Incorrect usage:

  ORACGCMD onlineorac 
  sales/CLUSTER=ntclu-150/USER=smith/PWD=smithpwd/DOMAIN=newengland
  Invalid syntax: no cluster name.
  For help, type "OracgCmd ?"
  
  

• Use the Windows Event Viewer to display events that have been reported during the processing of ORACGCMD commands.

Command Examples

Example 1

The following command places online an Oracle Real Application Clusters database instance named Sales1:

ORACGCMD onlineresource Sales1 /CLUSTER=ntclu-160 /USER=smith /PWD=smithpwd 
/DOMAIN=newengland

Example 2

The following command verifies all groups on the cluster NTCLU-150 and writes verify operation output to the log file C:\temp\verifygroups.log:

ORACGCMD verifyallgroups /CLUSTER=ntclu-150 /USER=smith /PWD=smithpwd 
/DOMAIN=ORANT /LOGFILE=c:\temp\verifygroups.log 

Example 3

The following command takes the Oracle Real Application Clusters database offline immediately:

ORACGCMD offlineorac sales /CLUSTER=NTCLU-150 /USER=smith /PWD=smithpwd 
/DOMAIN=ORANT /OFFLINE=immediate

Script Example

The following script backs up a database called db.world. This example assumes the database is contained in a group called FS Group1 running on a cluster called NTCLU-150, on node NTCLU-151.

REM   This script shows an example of performing a backup operation on an Oracle 
REM   Real Applications database. 

REM    


REM   1. Take the database offline.

ORACGCMD offlineorac sales /offline=immediate /cluster=NTCLU-150

REM   2. Begin the backup operation here. As an example, the following lines

REM    copy files using the copy function on the operating system.

copy e:\ofsdb\sales1\data\*.ora e:\backup\data
copy e:\ofsdb\sales1\log\*.ora e:\backup\log
copy e:\ofsdb\sales1\param\*.ora e:\backup\param
copy e:\ofsdb\sales2\data\*.ora e:\backup\data
copy e:\ofsdb\sales2\log\*.ora e:\backup\log
copy e:\ofsdb\sales2\param\*.ora e:\backup\param


REM   4. Place the database back online.

ORACGCMD onlineorac sales /cluster=ntclu-150

REM   The backup operation is complete.