5 The FSCMD Command-Line Interface

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

Note:

The FSCMD interface will be deprecated in a future release. It is presently replaced by the PowerShell cmdlets described in Chapter 6.

FSCMD

The FSCMD command enables you to perform many operations that you can perform with Oracle Fail Safe Manager. To run the FSCMD command, specify the full path, beginning with the location where Oracle Fail Safe Manager is installed: Oracle_Home\Failsafe\Client\fscmd.exe.

If you do not use this path, then the Windows operating system is not able to locate the FSCMD command.

Format

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

FSCMD action name /CLUSTER=cluster-name [qualifier]

Note:

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

Description

Oracle Fail Safe supplies the FSCMD command, which can be used in scripts to do many functions that can be done with Oracle Fail Safe Manager. For example, you can use the FSCMD command to take cluster resources offline before you perform nightly backups, and then place the resources online again when the backups are complete.

The FSCMD command can be run on any system where Oracle Fail Safe Manager is installed. (The FSCMD software is a component of Oracle Fail Safe Manager.)

When you run the FSCMD command, you can specify the name of a log file to capture the results of long-running operations.

Command Parameters

The following are some command parameters.

action

Specifies the action that can be 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 FSCMD ENABLEISALIVE command.

  • The instance is placed online.

The Verify Group command displays a warning if it finds that Is Alive polling is disabled for an instance, but it does not enable Is Alive polling again.

When Is Alive polling is disabled, the resource DLL writes a warning event to the Windows Event Log to indicate that database polling is disabled.
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 FSCMD 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.
ONLINEGROUP Places the group online.
ONLINERESOURCE Places the resource online.
OFFLINEGROUP Takes the group offline.
OFFLINERESOURCE Takes the resource offline. For Oracle Database resources, this operation requires the /OFFLINE command qualifier.
VERIFYGROUP Verifies a single group configured by Oracle Fail Safe. Output from this operation is written to the file name that is specified with the /LOGFILE qualifier.
VERIFYALLGROUPS Verifies all groups configured by Oracle Fail Safe. Output from this operation is written to the file name that is specified with the /LOGFILE qualifier.
VERIFYCLUSTER Verifies the cluster configuration. Output from this operation is written to the file name that is specified with the /LOGFILE qualifier.

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

name

The name of the resource or group on which you want the FSCMD command to take action. For example, PERSONNEL.world is a valid name for a single-instance database resource.

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

Command Qualifiers

The following are some command qualifiers.

/CLUSTER=cluster-name

Specifies the name of the cluster on which the FSCMD command will run.

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, or VERIFYALLGROUPS action is performed. If you do not specify the LOGFILE qualifier, then the log file is written to the current output device, which is typically the system console.

This qualifier is optional.

/NODE=node-name

Use this qualifier only with the MOVEGROUP action to specify the name of the node where you want to move a group.

This qualifier is required when you specify the MOVEGROUP action.

/OFFLINE=offline-option

Use this qualifier only when you specify the OFFLINERESOURCE action to take an Oracle resource offline. For Oracle Databases, if you do not supply one of the offline-option modes from the following table, then the resource is taken offline in the immediate mode (the default):

Mode Description
Abort Shuts down a database instantaneously by aborting the database instance. If possible, use the abort mode of shutdown only in the following situations:

  • The database or one of its applications is functioning irregularly and neither the immediate nor the normal mode of shutdown works.

  • You must shut down the database 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 immediately by terminating SQL statements in progress, rolling back uncommitted transactions, and disconnecting users. The immediate mode is the default mode to take a resource offline. If possible, choose the immediate mode only in the following situations:

  • A power shutdown is going to occur soon.

  • The database or one of its applications is functioning irregularly.

  • You are preparing to perform a database backup operation.
Normal Shuts down a database by:

  • Disallowing new connections after the database shutdown command is entered

  • Waiting for all connected users to disconnect before actually shutting down the database
Transactional Shuts down the database only after all of the current transactions have completed.

/DOMAIN=domain-name

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

/PWD=password

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

/USER=username

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

Usage Notes

The following are some FSCMD command usage notes:

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

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

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

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

  • Authentication information (domain, user name or password) for the FSCMD utility is optional. If no authentication information is supplied, then FSCMD attempts to connect to the server using its default local authentication information. If any authentication is specified on the command line (domain, user name or password) but one of the items is missing, then FSCMD prompts for the missing information. For example, when an FSCMD command is entered, if the /domain and /username switches are present but the /password switch is not provided then FSCMD displays a prompt asking for the user to supply the password; the password does not echo to the console.

  • 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:

    FSCMD onlineresource salesdb.world /CLUSTER=ntclu-160 /USER=smith /PASSWORD=smithpwd  /DOMAIN=newengland

    Incorrect usage:

    FSCMD onlineresource salesdb.world/CLUSTER=ntclu-160/USER=smith/PWD=smithpwd/DOMAIN=newengland
Invalid number of parameters.

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

Command Examples

The following are some command examples.

Example 1   

The following command places online an Oracle Database named salesdb.world:

FSCMD onlineresource salesdb.world /CLUSTER=ntclu-160 /USER=smith /PWD=smithpwd /DOMAIN=newengland
Example 2   

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

FSCMD verifyallgroups /LOGFILE=c:\temp\fsverify.log /CLUSTER=ntclu-160
 /USER=smith /PWD=smithpwd /DOMAIN=ORANT
Example 3   

The following command takes the Oracle Database offline immediately:

FSCMD offlineresource salesdb.world /CLUSTER=NTCLU-160 /USER=smith
 /PWD=smithpwd /DOMAIN=ORANT /OFFLINE=immediate
Example 4   

The following command takes a group called Disk Group 1 offline:

FSCMD offlinegroup "Disk Group 1" /CLUSTER=ntclu-160 /USER=smith /PWD=smithpwd /DOMAIN=ORANT

Script Example

The following script performs an online backup of a database called db.world. This example assumes the database is contained in a group called FS Group1 running on a cluster called NTCLU-140, on node NTCLU-141. (To perform a closed backup of the database, use the FSCMD offlineresource command to take the database resource offline in Step 2, and place it online in Step 6 using the FSCMD onlineresource command, instead of disabling and enabling Is Alive polling.)

REM   This script shows an example of performing an online backup operation
REM   on an Oracle Fail Safe database. 
REM    
REM   1. Move the group FS Group1 that contains the database to the node on 
REM   which the backup operation will run. Alternatively, you can create file
REM   share resources for each cluster disk to let the backup software 
REM   access the drives through a virtual server address regardless of which 
REM   cluster node currently owns them.

fscmd movegroup "FS Group1" /node=NTCLU-141 /cluster=NTCLU-140 /USER=smith
 /PWD=smithpwd /DOMAIN=ORANT

REM   2. Disable Is Alive polling for the database resource. This step allows
REM      you to keep the database online during the backup operation, but 
REM      prevents Oracle Fail Safe from attempting to fail over the database
REM      during the online backup operation.

fscmd disableisalive db.world /cluster=NTCLU-140 /USER=smith /PWD=smithpwd /DOMAIN=ORANT

REM   3. Mark the beginning of the online tablespace backup operation for each
REM      database tablespace. In this example there are two tablespaces, users
REM      and indx. The database must be in ARCHIVELOG mode to back up the 
REM      tablespaces. (If you use Recovery Manager (RMAN) for the online 
REM      backup operation, you are not required to mark the beginning
REM      and end of the tablespace backup operations, nor would you copy the 
REM      database files, as described in steps 3, 4, and 5.)

SQL> ALTER TABLESPACE users BEGIN BACKUP;
SQL> ALTER TABLESPACE indx BEGIN BACKUP;

REM   4. When you are certain the previous operations have completed, begin the
REM      backup operation. As an example, the following lines
REM      copy files using the copy function of the operating system.

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

REM   5. Indicate the end of the online backup operation of each tablespace.

SQL> ALTER TABLESPACE users END BACKUP;
SQL> ALTER TABLESPACE indx END BACKUP;

REM   6. Reenable Is Alive polling for the database resource.

fscmd enableisalive db.world /cluster=ntclu-140 /USER=smith /PWD=smithpwd /DOMAIN=ORANT

REM   The backup operation is complete.