symioctl

Sends I/O control commands to a specified application.

SYNOPSIS symioctl -type <DbType> [-h] [-noprompt] begin backup [<object> [<object>...]] [-checkpoint] freeze [<object> [<object>...]] [-checkpoint] checkpoint [<object> [<object>...]] end backup [<object> [<object>...]] thaw [<object> [<object>...]] archive log begin snapshot <object> SAVEFILE <SaveFile>

[-checkpoint] [-overwrite] restore snapshot <object> SAVEFILE <SaveFile>

[-norecovery | -standby] end snapshot <object> abort snapshot <object>

DESCRIPTION

The symioctl command allows control actions to be sent to a specified application. This utility is intended to be used in conjunction with a split operation.

The symioctl freeze command suspends updates from writing to disk. Once the freeze action completes, you can perform a TimeFinder or SRDF split. After the

Chapter 1: SYMCLI Commands

symioctl 393

Chapter 1: SYMCLI Commands split is complete, use the command symioctl thaw to resume normal application activity.

Additionally, for Oracle, Hot Backup control of all tablespaces to be backed up must be performed before and after a freeze/thaw command. The steps to split a group of BCV devices are:

1. symioctl begin backup

2. symioctl freeze

3. Split standard and BCV pairs.  This may involve several steps depending on your environment.

4. symioctl thaw

5. symioctl end backup

For SQLServer 2000 or higher, the snapshot commands support the SQLServer BACKUP and RESTORE database with snapshot operations using the Virtual Device

Interface (VDI). The database can be restored in recovery, norecovery, or standby mode.

The database user login information must be supplied using the SYMCLI_RDB_CONNECT environment variable. 

The user login information is specified in the following format: username/password@service. 

The username and password must be non-NULL.

If the NT trusted authentication is used, the user login information is specified in the following format: @sqlservername.

The object list  is not always required, as shown in the following table:

Action          RDBMS        Objects           List

------------- ----------- --------------- ----

Freeze/         Oracle       database server   No

Thaw            SQL Server   database name     Yes

394 EMC Solutions Enabler CLICommand Reference

Informix     database server   No

IBM DB2/UDB  database name     Yes

Sybase     database name     No

Checkpoint      Oracle       database server   No

SQL Server   database name     Yes

Informix     database server   No

Begin/End       Oracle       tablespace        Yes

Hot Backup

Archive Log     Oracle       database server   No

Begin/End       SQLServer    database name     No

Abort/Restore

Snapshot

Important Note: The user of the symioctl command must have database administrator privileges.

To execute the symioctl utility, you must have the appropriate application software installed and the environment variables set.

You can specify the database type information from an environment variable. The command line option takes priority over the follwoing environment variable:

Environment      Can be Used     To Specify

Variable         Instead of

--------------- -------------- -------------------

SYMCLI_RDB_TYPE  -type           Application type to perform requested action.

If an argument specified on the command line contains special shell characters (e.g., $, ', \\, etc.), those characters must be escaped with a backslash (\\).

Chapter 1: SYMCLI Commands

symioctl 395

Chapter 1: SYMCLI Commands

If symioctl is being run in client/server mode, and the required RDBMS environment variables are set in the client's environment, they are sent to the server to be used.

For IBM UDB/DB2, if the user tries to freeze all user databases' I/O while one or more databases' I/O have already been frozen, the freeze operation will fail.

ARGUMENTS abort snapshot

For SQLServer 2000 and higher. The

BACKUP DATABASE SQL command for the specified database will terminate and database writes will resume.

archive log    Archives the current log. This is an

Oracle-specific command.  begin backup   Places the specified tablespace objects into Hot Backup mode. This is an

Oracle-specific command.

begin snapshot For SQLServer 2000 and higher. A BACKUP

DATABASE TO VIRTUAL_DEVICE WITH SNAPSHOT

SQL command is sent to SQLServer which will begin the snapshot backup and suspend writes for the specified database. After the BCV mirrors are split, the end snapshot command should be issued to save the snapshot meta-data to a file.

checkpoint     Issues a checkpoint to the RDBMS.

end backup     Ends the Hot Backup for the specified

396 EMC Solutions Enabler CLICommand Reference

tablespace objects. This is an Oraclespecific command.

end snapshot   For SQLServer 2000 and higher.

The "BACKUP DATABASE" SQL command for the specified database will complete, database writes will resume and the snapshot meta-data will be saved to the save-file

(which is needed for a subsequent snapshot restore).

freeze         Suspends I/O at the application layer. 

Each application has a slightly different behavior, but they all provide a mechanism to halt modifications while a split operation occurs.

restore snapshot

For SQLServer 2000 and higher.

A "RESTORE DATABASE FROM VIRTUAL_DEVICE

WITH SNAPSHOT" SQL command for the specified database is sent to

SQLServer. The previously saved snapshot meta-data is used by

SQLserver to logically restore the database. The -norecovery and -standby options allow the RESTORE to operate in NORECOVERY or STANDBY mode. The undo file for -standby option is automatically generated. It is in the same location as the savefile with the file name undo_(database name).ldf.

thaw           Resumes I/O at the application layer.

OPTIONS

Chapter 1: SYMCLI Commands

symioctl 397

Chapter 1: SYMCLI Commands

-checkpoint    Requests a checkpoint prior to the specified action.

-h             Provides brief, online help information.

-noprompt      Turns off the prompt for user confirmation.

-norecovery    Restores an SQLServer database with the

NORECOVERY option.

-overwrite     Allows the backup process to overwrite an existing save file. By default, existing save files are protected.

-standby       Restores the SQLServer database with the

STANDBY option.

-type          Identifies the database type on which to perform the requested action. Types include: Informix, Oracle, SQLServer,

IBMUDB, and Sybase.

PARAMETERS object         Database or tablespace name(s). If no objects are specified, the action defaults to all objects of the specified type database.

SaveFile       For SQLServer snapshot only. Name of the save file used by begin snapshot and restore snapshot. For client/server mode, the meta-data file is saved by the server.

It is recommended that an absolute path

(e.g. C:\\TEMP\\PUBS.SAV) be specified

(especially for client/server) to ensure

398 EMC Solutions Enabler CLICommand Reference

that the file can be located for protection or subsequent restores.

RETURN CODES

Code #     Code Symbol

------ -----------

0        CLI_C_SUCCESS

1        CLI_C_FAIL

EXAMPLES

The following example will backup and then restore the

SQLServer pubs database on a group of BCV devices. The snapshot meta data will be saved in C:\\TEMP\\PUBS.SAV.

The database login parameters will be set via the environment to be user = sa, passwd = pass and service = sqlserv. Do the following: setenv SYMCLI_RDB_CONNECT "sa/pass@sqlserv" setenv SYMCLI_RDB_TYPE SQLServer symioctl begin snapshot pubs SAVEFILE C:\\TEMP\\PUBS.SAV

Split standard and BCV pairs.

symioctl end snapshot pubs

Protect the PUBS.SAV save file.

- - - - -

Restore the PUBS.SAV save file.

Shut down SQLServer.

Restore the standard devices from BCVs.

Restart SQLServer.

symioctl restore snapshot pubs SAVEFILE

C:\\TEMP\\PUBS.SAV

To freeze all the I/O in the Oracle instance represented by the connection information without prompting for

Chapter 1: SYMCLI Commands

symioctl 399

Chapter 1: SYMCLI Commands confirmation, enter:  setenv SYMCLI_RDB_CONNECT "scott/tiger" symioctl freeze -type Oracle -noprompt -checkpoint

The database will perform a checkpoint prior to executing the freeze command.  The database login parameters will be set via the environment to be user = scott and passwd = tiger.  

To thaw all the I/O in the Oracle instance represented by connection information, enter: setenv SYMCLI_RDB_CONNECT "scott/tiger@acme" symioctl thaw -type Oracle

The database login parameters will be set via the environment to be user = scott, passwd = tiger and service = acme.

To place all tablespaces in the Oracle instance represented by connection information into Hot Backup mode, enter: setenv SYMCLI_RDB_TYPE oracle symioctl backup begin -noprompt

The database type parameter will be set via the environment.

To archive the current log of the Oracle instance represented by connection information, enter: setenv SYMCLI_RDB_TYPE oracle symioctl archive log -noprompt

The database type parameter will be set via the environment.

400 EMC Solutions Enabler CLICommand Reference

To freeze I/O for the Informix database without prompting for confirmation, enter:  setenv SYMCLI_RDB_CONNECT "infadm/pass@infserv" symioctl freeze -type Informix -noprompt

The database login parameters will be set via the environment to be user = infadm, passwd = pass, and service = infserv.

To perform a checkpoint for the Informix database, enter:  setenv SYMCLI_RDB_TYPE informix symioctl checkpoint

The database type parameter will be set via the environment.

Chapter 1: SYMCLI Commands

symioctl 401