Administering Your DocuVault Using the db_prog Utility
The db_prog utility enables you to perform many administrative functions, including renaming the DocuVault, emptying the DocuVault, and repairing the entire DocuVault or individual DocuVault tables. In addition, the utility provides commands that help you control system backup and recovery.
This topic provides tasks you can perform using the db_prog utility.
Overview
The db_prog utility enables you to modify or manipulate a DocuVault. It is important that you are familiar with the db_prog utility prior to attempting any DocuVault management functions.
To enter a db_prog utility command
- Open a command prompt window, and change the working directory to the Cypress Server directory.
You are ready to use the db_prog utility and its commands.
To access help for the db_prog utility
- Open a command prompt window, and enter this command:
db_prog ?
This table describes the commands available for use with db_prog:
db_prog Command |
Description |
||||||
Changes the DocuVault status from offline dumping to clean after an offline backup completes, indicating that the DocuVault is ready for use. To use this command, you must have the DocuVault in offline dump mode. See Ending Offline Dump Modefor more information. |
|||||||
Cancels an online dump that has already started. To use this command, you must have the DocuVault in online dump mode and stop the Cypress Hub Service. |
|||||||
Cancels a scan if it does not complete successfully. This command changes the DocuVault status from scan to dirty, indicating that the DocuVault is in need of recovery. If you do not use this command, the DocuVault will not recover. To use this command, you must first stop the Cypress Hub Service. See To cancel a scan for more information. |
|||||||
Changes the IP address of the specified DocuVault. To use this command, you must first stop the Cypress Hub Service. See Changing the IP Address of a DocuVault for more information. |
|||||||
Allows a completed partition to be moved to a new directory. To use this command, you must first stop the Cypress Hub Service. |
|||||||
Adds the logged-on user to the Super Role list. You must run this command from the Cypress Server. See Reclaiming Super Rolefor more information. |
|||||||
Moves all log files from the finished directory into the collected directory, ensuring that the server can back up all finished log files while the DocuVault is running. See Performing a Log File Backupfor more information. |
|||||||
Creates a control file and installs the DocuVault. Enter the command in this form: db_prog create <log file path> <log file size> <cache memory size> <DV name> dump Or db_prog create <log file path> <log file size> <cache memory size> <DV name> delete where: <log file path> is the full path of the root directory in which log files are stored. Cypress will create several subdirectories under this root directory. <log file size> is the file size (in bytes) at which a log file is full. This value must be at least 1,000,000 bytes. |
|||||||
|
<cache memory size> is the size of the database cache (in bytes). This value must be at least 1,638,400 bytes. <DV name> is the name of the DocuVault (at most, 32 characters). dump saves log files for log file backups. delete discards log files that are no longer needed. To use this command, you must stop the Cypress Hub Service, and the existing collateral and log file directories, if any, must be empty. |
||||||
Disables or re-enables the Secure Sockets Layer (SSL) for the current DocuVault. To use this command, you must first stop the Cypress Hub Service. You must also be a member of the local Administrators or Power Users group. |
|||||||
Displays the current status of the DocuVault control file. If you execute this command when the DocuVault is in online or offline dump mode, the command will display the beginning log file number required to rebuild your DocuVault from the last full backup. To use this command, you must stop the Cypress Hub Service. See Displaying the Current DocuVault Statusfor more information. |
|||||||
Deletes all documents, job tickets, and history log messages from the current DocuVault. Cypress will retain all other settings. To use this command, you must first stop the Cypress Hub Service. See Emptying the DocuVaultfor more information. |
|||||||
enable_page_sysinx |
Enables the page-level system indexes if the DocuVault is already upgraded to Cypress 7.3 or above. |
||||||
logging_service |
Enables or disables the logging service, which tracks changes to the Cypress configuration. |
||||||
Puts the DocuVault in a clean state if it terminated in a dirty state, which happens if Cypress could not completely clean up the DocuVault before the system shut down. In most cases, Cypress automatically attempts to recover a dirty DocuVault upon startup. You will only occasionally need to run this command explicitly. See Cleaning a DocuVaultfor more information. |
|||||||
When Cypress migrates security IDs (SIDs), it retrieves the SID defined on the Identity tab for each recipient and verifies whether that SID is available in Active Directory. If it is, Active Directory will return it. If the SID is not available, then it has not been migrated yet and is skipped. If Active Directory returns an SID, the program will compare it with the one retrieved from the Address Book.
To use this command, you must first stop the Cypress Hub Service. |
|||||||
Creates a resource backup of the current DocuVault. To use this command, you must first stop the Cypress Hub Service. See Performing an Offline Resource Backupfor more information. |
|||||||
Stores the DocuVault’s name and IP address in Active Directory. To successfully publish a DocuVault to Active Directory, the user ID for the user publishing the DocuVault must have privileges that allow them to Create All Child Objects on the target Cypress server.
See Publishing a DocuVaultfor more information. |
|||||||
First retrieves an SID from the Address Book and searches for it in Active Directory. If the SID does not exist in Active Directory, then it has not been migrated yet and will be skipped. If Active Directory returns an SID, the program will compare this SID with the SID retrieved from the Address Book.
To use this command, you must first stop the Cypress Hub Service. |
|||||||
Rebuilds the DocuVault from a series of log files. Enter the command in this form: db_prog rebuild_through_log <most recent log #> where <most recent log #> is the highest log file number in the logs\db_prog.exe_collateral directory. |
|||||||
Removes a DocuVault from an existing pool. Enter the command in this form: db_prog remove_dv_from_pool <DocuVault name> where <DocuVaultname> is the name of the DocuVault to be removed. See Removing a DocuVault from a Poolfor more information. |
|||||||
Redistributes records of an existing page_segment table into new page_segment_n tables, allowing you to remove the old page_segment table. This command reduces the original table’s file data size by 10MB blocks during processing and can be run multiple times until the existing page_segment table is empty. You can stop the processing by entering the stop_remove_page_table command or Ctrl+C. See Removing a page_segment Tablefor more information. |
|||||||
remove_pool_info | Removes all pool information from this DocuVault. This DocuVault must be removed from the pool, and the other DocuVaults updated to reflect this, before the remove_pool_info command is used. | ||||||
Renames the DocuVault. To use this command, you must first stop the Cypress Hub Service. See Renaming a DocuVaultfor more information. |
|||||||
Optimizes the way in which Cypress allocates information in any of the listed tables. See Repacking a DocuVault Tablefor more information. |
|||||||
Repairs the DocuVault. Use this command only when directed to by ASG Customer Support. To use this command, you must first stop the Cypress Hub Service. See Repairing a DocuVaultfor more information. |
|||||||
Repairs a single table in the DocuVault. Use this command only when directed to by ASG Customer Support. See Repairing a DocuVault Tablefor more information. |
|||||||
reset_service_config |
Resets the Authentication service to the default value. |
||||||
reset_window_auth_type | This command resets the Windows authentication type to the “system default” value, and would be needed if you change the Authentication type to a value (Kerberos for example) that was not available on your system. If you perform this operation, you would not be able to get back in through the UI, and thus unable to change it back – you would be locked out permanently. This db_prog command resets the value in the DocuVault, so you can then get back in through the UI. | ||||||
Restores the Cypress DocuVault from a clean online backup. To use this command, you must first stop the Cypress Hub Service and load the control file and data files from a clean online dump of the Cypress DocuVault. |
|||||||
Restores an empty DocuVault from a resource backup. To use this command, you must first stop the Cypress Hub Service. See Performing an Offline Resource Backupfor more information. |
|||||||
Resumes all suspended devices in the Cypress DocuVault. To use this command, you must first stop the Cypress Hub Service. You must also be a member of the local Administrators or Power Users group. |
|||||||
Rolls back the uncompleted partition if an attempt to create a partition fails. |
|||||||
Verifies the validity of the data records and key fields within an entire DocuVault or a specific table. ASG recommends that you run db_prog utility with this command occasionally as part of your backup cycle to identify problems as soon as they occur. Use the recover_dr_only option only when instructed to do so by ASG Customer Support. You can review all scan processing information in the process.log file, which is located in the Cypress Server\db_prog.exe_collateral directory. To use this command, you must first stop the Cypress Hub Service. See Validating DocuVault Integrityfor more information. |
|||||||
By default, the Chinese full-text Indexing feature is disabled.
set_chinese_index_option enable Make sure the Asian Language Word Segment Engine component is installed on the Cypress Server before enabling this option.
set_chinese_index_option disable To use this command, you must first stop the Cypress Hub Service. |
|||||||
Sets the document replication option for Cypress DocuVault pools. By default, Cypress duplicates documents sent to remote DocuVaults.
set_dv_pool_option default
set_dv_pool_option no_ddoc_ To use this command, you must first stop the Cypress Hub Service. |
|||||||
Sets the maximum retention time for replicated documents. To use this command, you must first stop the Cypress Hub Service. |
|||||||
Enables Server-side Security in the current DocuVault. See Enabling Server-side Security for more information. |
|||||||
Marks the DocuVault status as offline_dumping and moves all log files to the collected directory for backup. Issue this command before performing a full Cypress backup. |
|||||||
stop_remove_page_table |
Stops the remove_page_table command processing. You can restart the processing later, if desired. You can also stop the processing by entering the Ctrl+C. |
||||||
Suspends all devices in the DocuVault. When you start the DocuVault, all devices will be suspended, allowing administrators to correct any problems before resuming normal operations. To use this command, you must first stop the Cypress Hub Service. See Suspending All Devices for more information. |
|||||||
Removes the DocuVault from Active Directory. To successfully unpublish a DocuVault from Active Directory, the user ID for the user unpublishing the DocuVault must have privileges that allow them to Create All Child Objects on the target Cypress server.
See To unpublish a Cypress DocuVault from Active Directoryfor more information. |
|||||||
Updates the control file with new installation parameters. Enter the command in this form: db_prog update <log file path> <log file size> <cache memory size> <DV name> dump Or db_prog -update <log file path> <log file size> <cache memory size> <DV name> delete where: <log file path> is the full path of the root directory in which log files are stored. Cypress will create several subdirectories under this root directory. <log file size> is the file size (in bytes) at which a log file is full. This value must be at least 1,000,000 bytes. <cache memory size> is the size of the database cache (in bytes). This value must be at least 1,638,400 bytes. |
|||||||
|
<DV name> is the name of the DocuVault (at most, 32 characters). dump saves log files for log file backups. delete discards log files that are no longer needed. You can substitute an asterisk (*) for any parameter that you do not wish to change. To use this command, you must stop the Cypress Hub Service. |
||||||
upgrade_keep_page_sysinx |
Keeps the page-level system indexes when you upgrade to Cypress 7.3 or above from a release earlier than 7.3. |
||||||
Identifies errors in your database files, including any missing files and timestamp mismatches. You must stop the Cypress Hub Service if the file directory you are validating is the Server\ For more information, see Validating Database Files. |
Displaying the Current DocuVault Status
You can use the display_db_status command to display the current status of your DocuVault.
If the DocuVault is currently in online or offline dump mode, executing this command will also display the beginning log file number required to rebuild your DocuVault from the last full backup.
To display the status of your DocuVault
> | Enter this command string at the command prompt: |
The current status of the DocuVault is displayed on the db_prog window.
Validating DocuVault Integrity
You can use the db_prog scan dv command to validate your DocuVault’s integrity.
The db_prog scan dv command enables you to verify the validity of the data records and key fields within a DocuVault. ASG recommends that you run this utility periodically as part of the backup cycle to identify problems as soon as they occur. You can specify several parameters when running the db_prog scan dvutility.
To scan and validate the entire DocuVault
> | Enter this command: |
db_prog scan dv
To scan and validate the entire DocuVault, and terminate the scan as soon as an error occurs
> | Enter this command: |
db_prog scan dv unattended_scan
To scan and validate only DocuVault data files, omitting all index files
> | Enter this command: |
To recover the DocuVault when it terminates in a dirty state
> | Enter this command: |
db_prog scan dv recover_dr_only
To scan and validate a specific database table
> | Enter this command: |
db_prog scan dv table <table name>
where <table name> corresponds to the name of the table you wish to validate.
If a scan command unexpectedly terminates–for example, if you shut down the Cypress Server while it is performing a scan–you can cancel the scan to change the status of the DocuVault from scanning to dirty so that a system recovery can successfully complete.
> | Enter this command: |
db_prog cancel_scan
Validating Database Files
You can use the db_prog validate_db_files command to identify errors in your database files, including any missing files and timestamp mismatches. You can further validate your database files by specifying the directory and the scope of the verification.
To validate database files in the Server\db_prog.exe_collateral directory
You can execute this command only when the Cypress Hub Service is stopped. It scans all database files in the Server\db_prog.exe_collateral directory. If you want to specify a directory and the scope of the validation, see To specify the scope of validation for database files in a specific file directory .
> | Enter this command: |
To specify the scope of validation for database files in a specific file directory
If you specify a directory other than the Server\db_prog.exe_collateral directory, you can execute this command when the Cypress Hub Service is running.
> | Enter this command: |
db_prog validate_db_files file_dir=<file path> scope=<verify_scope>
where:
<file path> is an optional parameter that specifies the directory for which database files are to be validated. If you do not specify a directory, the default is the Server\db_prog.exe_collateral directory.
<verify_scope> is an optional parameter that specifies the scope of the validation to be performed. These are the valid parameters:
• | The default parameter specifies that all data base files be verified for file existence and size, updated timestamp, and self identification. If you do not specify a parameter, this setting is used for the verification. |
• | The content parameter specifies that the default verification be performed on all database files. Additionally, it validates the contents of each file, including checksum and the self identification for each data block. |
• | The backup parameter ensures that all database files are good for a DocuVault backup. It specifies that the default verification be performed on all database files. Additionally, it validates the contents of each file. The database status in the control file (i.e., control_file.cdb) must be clean or dumping. |
To stop validation of database files if an error occurs
You can stop verification when the first error occurs by entering this command. Otherwise, the verification process continues, and all errors are written to the pcon_log file.
> | Enter this command: |
db_prog validate_db_files stop_on_error
Or
db_prog validate_db_files file_dir=<file path> scope=<verify_scope> stop_on_error
where:
<file path> is an optional parameter that specifies the directory for which database files are to be validated. If you do not specify a directory, the default is the Server\db_prog.exe_collateral directory.
<verify_scope> is an optional parameter that specifies the scope of the validation to be performed. These are the valid parameters:
• | The default parameter specifies that all data base files be verified for file existence and size, updated timestamp, and self identification. If you do not specify a parameter, this setting is used for the verification. |
• | The content parameter specifies that the default verification be performed on all database files. Additionally, it validates the contents of each file, including checksum and the self identification for each data block. |
• | The backup parameter ensures that all database files are good for a DocuVault backup. It specifies that the default verification be performed on all database files. Additionally, it validates the contents of each file. The database status in the control file (i.e., control_file.cdb) must be clean or dumping. |
Maintaining Your DocuVault
This topic provides db_prog commands you can use to maintain your DocuVault.
Cleaning a DocuVault
You can use the db_prog make_clean command to enable you to clean DocuVaults if their shutdown procedures do not complete before system shutdown.
When a system shuts down before Cypress can completely clean up a DocuVault, the DocuVault terminates in a dirty state. You can use the make_clean command to put the DocuVault in a clean state. You will probably not need this utility, as Cypress automatically attempts to recover a dirty DocuVault upon start up, but it is provided as a handy tool.
To clean a dirty DocuVault
> | Enter this command at the command prompt: |
db_prog make_clean
Emptying the DocuVault
You can use the db_prog empty_dv command to empty the DocuVault.
On rare occasions, you might need to purge the DocuVault of all documents. For example, when you complete final testing on a newly created DocuVault, you probably will want to remove test data before moving the DocuVault to a production environment. You can accomplish this task by executing the db_prog empty_dvcommand. It removes all Cypress documents, job tickets, and document tickets from the DocuVault, while keeping all Cypress objects (e.g., formats, devices, and report definitions) intact.
To empty the DocuVault
> | Enter this command string at the prompt: |
db_prog empty_dv
Changing DocuVault Parameters
You can change these DocuVault parameters with the db_prog updatecommand:
• | Log file path |
• | Log file size |
• | DocuVault cache |
• | Log file disposition |
You can use the db_prog update command to alter one or more parameters at a time.
To update DocuVault parameters
> | Use this syntax: |
db_prog update <log file location> <log file size> <DocuVault cache> <log file disposition>
where:
<log file location> is the new location of the log file.
<log file size> is the new maximum size of the log file.
<DocuVault cache> is the new size of the DocuVault cache.
<log file disposition> is the new retention setting for the log file.
If you do not want to change a particular parameter, you can replace it with an asterisk.
Using the update Command
Updating the log file path. Before you update the log file path, move the current Cypress log file structure to the desired location. This example illustrates changing the log file path from one location to a new location:
db_prog update d:\cypress\logs * * *
Updating the log file size. The default log file size for all Cypress installations is 20 MB. This example illustrates changing the default log file size to 30 MB:
db_prog update * 30000000 * *
Updating the DocuVault cache. At the time of installation, Cypress calculates approximately 25 percent of the total memory available on the Cypress Server and sets the DocuVault cache to this number. The DocuVault cache size must be at least 1,638,400 bytes. Whenever you modify the total memory size on the server, you should adjust the DocuVault cache accordingly. This example illustrates changing only the DocuVault cache parameter:
db_prog update * * 262026000 *
Updating log file disposition. There are two settings for log file retention (disposition): dump and delete. In your production environment, ASG strongly recommends implementing the dump option to maintain all finished log files for backup and, ultimately, recovery in a disaster situation. Should the DocuVault encounter any critical problems and need to rebuild itself, logs are most often necessary.
In a test or development setting, however, some customers choose to implement the delete option because either recovery might not be critical, disk space might be limited, or backup procedures are not being implemented.
This example illustrates changing the log file disposition from delete to dump:
db_prog update * * * dump
Logging Service
Cypress can be configured to maintain a history of changes to the configuration, and allow for previously changed configurations to be reloaded.
To enable the logging service, enter the command:
db_prog logging_service enable localDV
“localDV” specifies that the change history is stored into the local DocuVault.
To disable the logging service, enter the command:
db_prog logging_service disable
Renaming a DocuVault
There are several reasons why you might have to change your Cypress DocuVault’s name, including a change in your employer’s organizational structure, a new server location, or DocuVault environment changes. You can use the db_prog rename_dv command to give your DocuVault a new name.
To change your DocuVault’s name
1. | Stop the Hub Service. |
2. | Open a command prompt window on the Cypress Server that you want to rename. Change the working directory to the Cypress Server directory. |
3. | Enter this command at the command prompt: |
db_prog rename_dv <new DocuVault name>
where <new DocuVault name> is the new name of the Cypress DocuVault.
4. | Restart the Hub Service. |
5. | Examine the db_prog window to verify that the new DocuVault name has taken effect, as shown: |
Changing the IP Address of a DocuVault
You can use the change_dv_ip_address command to specify a new IP address for a DocuVault.
To change the IP address of a DocuVault
> | Enter the command in this form: |
db_prog change_dv_ip_addr <dv_name> <new_ip_addr>
where:
<dv_name> is the name of the DocuVault for which you want to change the IP address.
<new_ip_addr> is new IP address to be used for the DocuVault.
Removing a DocuVault from a Pool
You can use the remove_dv_from_pool command to remove a DocuVault from a pool.
To remove a DocuVault from a pool
1. | Stop these DocuVaults, as appropriate to your situation: |
• | Each DocuVault in a peer-to-peer pool |
• | The master DocuVault and the slave DocuVault that is being removed in a master-slave pool |
2. | Run this command on each of the DocuVaults listed in step 1: |
db_prog remove_dv_from_pool <DocuVault name>
where <DocuVaultname> is the name of the DocuVault to be removed.
Publishing a DocuVault
Most customers publish Cypress DocuVaults to the Windows Server’s Active Directory upon installation. If, however, your installation did not publish your DocuVault to Active Directory, or you have since unpublished it, you can perform Active Directory registration manually.
To manually publish a Cypress DocuVault to Active Directory
1. | Open a command prompt window. Change the directory to the Cypress Server directory if necessary. |
2. | Optional. Determine whether you wish to include the DNS name when you publish Cypress to Active Directory. The inclusion of the DNS name can be useful if your Cypress Server is part of a cluster. |
3. | If you wish to include the DNS name, enter this command at the command prompt: |
If the DNS name includes one or more spaces, enclose it in quotation marks:
db_prog publish_dv “dns_name”
Or
If you do not wish to include the DNS name, you do not need to enter any parameters:
db_prog publish_dv
4. | Verify that the registration worked by opening your Cypress main user interface and clicking the Browse toolbar button . |
The DocuVault that you published should appear in the DocuVaults list.
To unpublish a Cypress DocuVault from Active Directory
1. | Open a command prompt window. Change the directory to the Cypress Server directory if necessary. |
2. | At the command prompt, enter this command: |
3. | Verify that the command worked by opening your Cypress main user interface and clicking the Browse toolbar button. |
The DocuVault that you unpublished should not appear in the DocuVaults list.
Suspending All Devices
Once you have started the Cypress DocuVault and, if the Hub Service is fully running, all jobs received by Cypress are processed. There are instances, however, in which you might not want to begin processing jobs immediately upon startup. For example, there may be prior errors that need to be resolved before resuming normal processing or erroneously created jobs that should be purged.
As an alternative to manually suspending devices immediately upon startup, you can issue the db_prog suspend_all_printers command in offline mode to mark all devices in the DocuVault as suspended. Then, when you bring up the DocuVault using the normal method, the devices will be suspended, enabling you to correct any problems before resuming normal operations.
To mark all devices as suspended
1. | Stop the Hub Service. |
2. | On the Cypress Server, open a command prompt window. |
3. | Change the working directory to your Cypress Server directory. |
4. | Enter this command: db_prog suspend_all_printers |
5. | Start the DocuVault. |
Reclaiming Super Role
Administrators can sometimes lose Super Role access privileges to a DocuVault. For example, Super Role or administrative user accounts can be deleted from the Windows user database, the DocuVault can be moved to another domain, or company reorganizations can cause administrative security changes.
The claim_super_role command deletes the current Super Role entry in the DocuVault and creates a new entry consisting of a single user—the currently logged-on Windows user—with all permissions.
To reclaim Super Role
1. | From the Cypress Server, log onto Windows using an account that has either administrator or power user privileges. |
2. | Stop the Hub Service by selecting Start } Cypress Server } Stop Hub. |
3. | Open a command prompt window, and change the working directory to the Cypress\Server directory. |
4. | Enter this command: db_prog claim_super_role |
5. | The Cypress Server update is now complete. If you registered Cypress as a Windows service, the Hub Service will start automatically when you reboot the machine. Select Start } Cypress Server } Start Hub to manually start Cypress. |
At this point, the currently logged-on Windows user is a Cypress Super Role user and can perform administrative actions and/or change security settings as required.
See Managing Cypress Security for more information on Cypress security.
Reset Authentication Service
Due to the configuration of the Authentication Service in the Administration > Parameter > Service screen and the Skip Integrated Windows Logon checkbox on the Administration > Parameter > Option screen, Cypress administrators may get locked out of the UI.
The db_prog reset_service_config command resets the Authentication service to the default configuration, which will then allow domain users to connect to the DocuVault.
Repairing a DocuVault
You can use the db_prog repair_dv command to repair your DocuVault. Use this command only under the guidance of ASG Customer Support.
In extreme cases, you might find it necessary to use the db_prog utility to repair a DocuVault before it can be restored. The repair procedures delete all DocuVault components (except the data files and control file) and then rebuild the DocuVault. The DocuVault will not be operational during the repair process.
You can use the repair_dv command to repair all database tables, all page indexes, or both simultaneously. Again, do not execute this command unless ASG Customer Support personnel instruct you to do so.
1. | Contact ASG Customer Support for assistance with the repair process. |
2. | Ensure that the Cypress Hub Service is stopped. If the DocuVault is in the state where it needs to be repaired, the Hub Service is most likely stopped anyway. If it is still running, however, enter this command from a command prompt: |
hub_service stop
3. | From a command prompt on the Windows server on which Cypress is installed, begin the repair process by changing the working directory to the Cypress Server directory and entering this command: |
The db_prog console window will open and display steps being performed to repair the DocuVault.
• | If successful, the last few lines in the console window will state that the procedure has completed and the DocuVault has been repaired. Continue to step 4. |
• | If unsuccessful, the console window will most likely indicate that an error has occurred. If you receive this message, do not attempt to restart Cypress; instead, proceed to step 5. |
4. | Restart Cypress as a Windows service. If the DocuVault still is not restored after executing this step, continue to step 5. |
5. | Repair the page index used by Cypress for archiving and indexing. From a command prompt on the Windows Server, enter this command: |
A command prompt will open and display messages related to repairing the page index. This generally takes about 30 seconds to one minute.
6. | Restart Cypress as a Windows service. |
7. | While the DocuVault is operational at this time, the page index is actually being repaired in background mode. Therefore, archived pages and indexes will not be immediately available. |
These commands enable you to perform specific repair tasks:
To repair the database tables
> | Enter this command: |
db_prog repair_dv db_tables
This command will repair the internal data tables that the DocuVault uses to reference objects and settings within the database. The amount of time the process requires is related to the size of your DocuVault. The DocuVault will be offline for the duration of the rebuild process.
To repair the page index tables
> | Enter this command: |
This command will repair the page index tables that refer to system, custom, and full-text indexes. The initial repair of a table takes only a few moments and is performed with the DocuVault offline. Once the Cypress service is restarted, the re-indexing of documents will begin. This is a processor-intensive task and the amount of time it requires is directly related to the number of documents indexed and the manner in which they are indexed.
To repair both database and page index tables
> | Enter this command: |
This command repairs both the internal data tables and the page index tables.
In some cases, you might need to repair tables that have files with timestamps that do not match.
To repair tables with nonmatching timestamps
> | Enter this command: |
db_prog repair_dv all ignore_timestamp
Managing DocuVault Tables
This topic provides instructions for repacking and repairing your DocuVault tables.
Repacking a DocuVault Table
Repacking a DocuVault table can provide you with faster access to records by sorting them into document order and then rebuilding the table without empty spaces. You can use the repack_tablecommand to optimize the way in which the DocuVault allocates information in any of five tables.
To repack a DocuVault table
> | Enter this command into a command prompt window from the Cypress\Server directory: |
db_prog repack_table <table name>
where <table name>is one of these values:
• | ddoc_inx_tables |
This table contains the index data. Records are created when a document is captured and indexed, then freed when the document is deleted or partitioned. Thus, doing a repack of ddoc_inx_tables after a partition frees up some disk space.
• | file_segment |
This command repacks the table that stores documents captured in native file format.
• | font_tables |
This table contains captured fonts. Cypress builds fonts for documents as they are needed. If a large number of documents containing document-centric fonts has since been deleted, a table repack can free some disk space.
• | page_segment |
This table consists of 16 smaller tables. The system references and modifies up to 16 records simultaneously. Records are created when documents are captured and freed when documents are deleted.
Refer to this table to determine which page_segment command you should use:
Command |
Description |
page_segment |
Repacks the old table from Cypress 5.5 and earlier. |
page_segment_n |
Repacks any of the 16 new tables, where n is the specified table (1 through 16). |
page_segment_all |
Repacks the old single table and all 16 new tables. |
• | resource_link |
This table contains information about the resources used by documents (e.g., fonts, stocks, and images). Records are created when documents are captured and freed when documents are deleted. If a lot of documents have been deleted recently, a repack reduces the amount of disk space being used.
• | system_msg |
This table contains the Cypress History messages. Since these messages are constantly created and deleted, a table repack will likely have minimal impact.
For example, enter this command to repack the page_segment table:
db_prog repack_table page_segment
This example shows the typical output from repacking a page_segment table:
Repairing a DocuVault Table
The db_prog repair_table command enables you to repair individual database tables. You should use this command only under the guidance of ASG Customer Support personnel.
To repair an individual database table
> | Enter this command: |
db_prog repair_table <table name>
where <table name>is the name of a table in the DocuVault.
This command will repair the internal data table specified by <table name>. The time required to process this command will vary depending on the size of your DocuVault. The DocuVault will be offline while Cypress rebuilds the table.
In some cases, you might need to repair the tables without making any changes to timestamps.
To repair a database table without validating its timestamps
> | Enter this command: |
db_prog repair_table <table name> ignore_timestamp
Removing a page_segment Table
This section provides the command used to redistribute records of an existing page_segment table into new page_segment_n tables, allowing you to remove the old page_segment table. It reduces the original table’s file data size by 10MB blocks during processing and can be run multiple times until the existing page_segment table is empty.
To redistribute records from the page_segment table
> | Enter this command: |
remove_page_table
You can stop the processing by entering the stop_remove_page_table command or Ctrl+C.
Moving a DocuVault
During periods of upgrade and reorganization, you might find it necessary to move a DocuVault either to a new disk on the Cypress Server or to a new machine.
Moving Your DocuVault To a New Disk
You might decide to move a DocuVault to a new disk on the current machine for a variety of reasons. For example, you might have upgraded a system or experienced a disk failure. Based on your specific circumstances, you might have to make one of these changes:
• | Move data files to a new location and write log files to a new location |
• | Move only data files to a new location and continue to write log files to their current location |
• | Write only log files to a new location and leave the data files in their current location |
This section discusses the procedures for all of these options. The step-by-step instructions will allow you to place the DocuVault in a clean state, perform a full backup, move data files (and associated Cypress service activities) to a new location, and update Cypress with the new location where log files are to be written.
To move the DocuVault to a new disk on the Cypress Server
1. | Stop the Hub Service. See Stopping the Hub Service for more information. |
2. | Open a command prompt window and enter this command: |
C:\Cypress\Server\db_prog.exe start_offline_dump
An offline dump updates the data files with log file information, creating a clean DocuVault.
3. | Perform a full backup of your DocuVault. |
4. | Delete all files in the directory <log file directory>\ db_prog.exe_collateral, where <log file directory> is the directory where your Cypress Server stores its log files. |
For example, if your logs are stored in the C:\Cypress\logs directory, delete all files from C:\Cypress\logs\db_prog.exe_collateral.
• | If you do not want to move your data files, then proceed to step 9. . |
• | If you want to move your data files, remove the Cypress Hub Service by selectingStart}Cypress Server } Hub Service (Remove) and continue to step 5. |
5. | From the command prompt window, enter this command: |
C:\Cypress\Server\clear_font.exe
Cypress is enabled to rebuild the font list after installation.
6. | Move your data files to the new location. In general, you should move the entire Cypress folder. |
7. | Update all Cypress shortcuts so that they point to the new location: |
a. | From Windows Explorer, navigate to C:\Documents and Settings\All Users\Start Menu\Programs\Cypress Server. |
b. | Right-click the first shortcut, and select Properties from the context menu. |
c. | Change the directory paths in both the Target and Start in input fields. |
d. | Click OK. |
Repeat this step for each shortcut in the directory.
8. | Reregister the Cypress Hub Service by selecting either Start } Cypress Server } Hub Service (Auto Start) or Start } Cypress Server } Hub Service (Manual), depending on whether you wish to start the Cypress Server automatically or manually. |
• | If you do not want to write log files to a new location, continue to step 9. |
• | If you want to write log files to a new location, enter this command from a Windows command prompt: |
db_prog update <log file location> * * *
where <log file location> is the directory in which you want your Cypress Server to write its log files.
For example, if you want to change the location of the log files to E:\Cypress\logs, enter this command:
db_prog update E:\Cypress\logs * * *
See Changing DocuVault Parameters for more information on the db_prog update command.
9. | To cancel the offline dump, enter this command from the command prompt window: |
c:\cypress\server\db_prog.exe cancel_offline_dump
10. | Restart Cypress by selecting Start } Cypress Server } Start Hub. |
Moving Your DocuVault To a New Machine
While the steps to move a DocuVault to a new machine are quite simple, understanding the specific tasks to be performed will help you plan the process. ASG encourages you to review all procedures before moving your DocuVault.
To move the DocuVault to a new machine
1. | Stop the Hub Service. See Stopping the Hub Service for more information. |
2. | Open a command prompt window, and enter this command: |
C:\Cypress\Server\db_prog.exe start_offline_dump
An offline dump updates the data files with log file information, creating a clean DocuVault.
3. | Perform a full backup of your DocuVault. |
4. | Disable the TCP/IP Print Server on the new machine. |
a. | Open the Windows Control Panel, and double-click the Administrative Tools icon. |
b. | From the Administrative Tools window, double-click the Services icon to display the Services dialog. |
c. | Right-click the TCP/IP Print Server in the Services list, and select Properties from the context menu. |
d. | Select Disabled from the Startup type drop-down list. |
e. | Click OK to close the Properties dialog. |
f. | Select File } Exit to exit the Services dialog. |
5. | Install Cypress on the new machine using your installation CD. |
6. | Stop the Hub Service on the new machine. |
7. | On the new machine, install any updates and/or patches received from ASG since the last full installation. |
8. | From the new machine, delete any files in the directory Cypress\Server\db_prog.exe_collateral. |
9. | Copy the contents of the directory Cypress\Server\db_prog.exe_collateral on the original machine to the corresponding directory on the new machine. |
10. | On the new machine, update the DocuVault cache size using the update command, if required. |
When moving a DocuVault to a new machine, you might need to recompute your cache requirements. If the amount of memory on the new machine is the same as the old machine, you need not perform this step. If the available memory on the new machine is different, however, you must update the DocuVault’s cache size. Allocating 25 percent of available memory to a DocuVault is a reasonable estimate for most platforms. If you wish to allocate over 50 percent of available memory, contact ASG Customer Support first to discuss your configuration.
• | If you do not wish to change the cache size, continue to step 11. |
• | If you wish to change the cache size, enter this command from a Windows command prompt: |
db_prog update * * <DocuVault cache> *
where <DocuVault cache> is the new cache size.
For example, to change the cache size to 20,000,000, bytes (2 MB), you would enter this command:
db_prog update * * 20000000 *
See Managing DocuVault Tables for more information on the db_prog update command.
11. | Start Cypress on the new machine by selecting Start } Cypress Server } Start Hub. |
Backing Up Your DocuVault
Before you begin to backup or restore a Cypress DocuVault, first familiarize yourself with the different files that Cypress uses to construct and maintain it. The files are critical to successful backup and recovery, so ASG strongly recommends that you understand the function of each file and its location on the server. You also should understand the types of backups that you can perform and establish a plan for routinely backing up critical Cypress data.
Cypress File Structure
The Cypress DocuVault is a database that contains a variety of information related to your output environment. This information is maintained in different files in different disk partitions on the Windows server. Cypress stores this information in two types of files: data files and log files.
Data files contain output environment settings (e.g., printer definitions, stocks loaded in printer trays, and documents). You can think of data files as a snapshot of your environment taken at a specific moment. Cypress does not, however, immediately update data files when you make changes to your output environment— this would result in excessive disk reads and writes that could degrade performance. Instead, Cypress immediately records all changes in RAM and simultaneously writes changes and events to a sequential log file. It updates the data files whenever it can perform the update most efficiently and stores the data files in the Server\db_prog.exe_collateral directory.
Cypress uses log files to record all events as they occur in the output environment. A log file records real-time events so that Cypress can later update the data files in the most efficient way. Cypress records every event (e.g., a stock change or job submission) on disk in a log file as it happens, creating a chronological record of all events. When a log file becomes full, Cypress writes the log file data to the data files, closes the log file, and starts a new log file.
Cypress initially writes a log file to the Logs\db_prog.exe_collateral directory until it is full. Cypress retains the log file in this directory until the DocuVault determines that it no longer needs the file for normal operation. Then, Cypress moves the log file to the Logs\db_prog.exe_finished directory.
To ensure that all log files are available for backup, you must move them from the Logs\db_prog.exe_finished directory to the Logs\db_prog.exe_collected directory at the time of backup. (Rather than moving them manually, you can run the db_prog collect_finished_logs utility. The online dump will also automatically move the logs for you.) This implementation solves an inherent problem associated with many popular backup software products that cannot back up a directory when its contents are changing during the backup operation.
Cypress also creates the control file, which is a unique type of data file important to rebuilding the DocuVault. The control file is a special type of data file that records the state of data files and log files (open or closed) at the time of a system failure. If the control file indicates that a log file was open, Cypress knows that it needs to read the log data in order to recover to the point at which the failure occurred. The control file is stored in the Server\db_prog.exe_collateral directory.
This table provides a summary of the directories that store data files, log files, and the control file:
Directory |
Function |
Logs\db_prog.exe_collateral |
Stores open log files as well as any full logs files needed for normal DocuVault operation. |
Logs\db_prog.exe_collected |
Stores log files moved from the db_prog.exe_finished directory. This is the only log file directory that you should back up when performing a log file backup. |
Logs\db_prog.exe_finished |
Stores closed log files that Cypress does not need for DocuVault operation. |
Server\db_prog.exe_collateral |
Stores data files and the control file. Back up this directory when performing a full backup. |
Types of Backups
Cypress offers four types of backups:
• | Offline DocuVault backups |
• | Online DocuVault backups |
• | Log file backups |
• | Offline Resource Backup |
You can use an offline backup to back up the entire DocuVault, including all data files, log files, and the control file. An offline backup allows you to restore Cypress to the exact point at which the backup took place. An offline backup can be performed, however, only after stopping the Cypress Hub Service and placing it in offline dump mode. This means that your users will not be able to access Cypress while you back it up. You will most likely want to schedule offline backups at off-peak hours.
Like the offline backup, you can use online DocuVault backups to back up the entire DocuVault, including all data files and the control file. An online backup allows you to restore Cypress to the exact point at which the backup took place. Unlike the offline backup, however, an online backup will allow you to back up data files while Cypress is still online and accessible to your users.
You can use a log file backup to back up data generated since the last online or offline backup. In the event of a disaster, the last backup and any subsequently backed-up log files can be used to restore the DocuVault to the point at which the last log file backup took place. Unlike with offline backups, you can perform log file backups while Cypress is running. They are completely transparent to your users. Log file backups provide a method and enable you to back up data at frequent intervals without disrupting operation.
You can use an offline resource backup to restore an empty DocuVault at a remote Disaster Recovery (DR) site. An offline resource backup allows you to quickly have a DocuVault up and running at your remote DR site. It does not process document-related information, which reduces the size of the backup and provides you with the capability to restore an empty DocuVault from a resource backup in a few minutes.
Performing an Offline Backup
The offline backup utility, or offline dump mode, allows you to back up the entire Cypress DocuVault, including all documents, security and device settings, and index information. Smaller companies that do not have a robust IT staff monitoring daily backup routines find it easier to use offline backup as there are few commands necessary. Executing the command for this feature closes off all open log files and backs up the database.
For normal or disaster recovery purposes, you can place the db_prog.exe_collateral directory on any machine and bring it up immediately without any migration of shadow files or rebuilding through logs. You will need to obtain a new license file. You must ensure that you have adequate disk space before you begin the offline backup. Typically, the amount of space required is equivalent to the size of the db_prog.exe_collateral directory.
Beginning Offline Dump Mode
To place a currently running local DocuVault in offline backup mode
1. | Stop the Hub Service by taking one of these actions: |
Open a command prompt, and enter one of these commands:
hub_service stop
net stop cypress
Or
Select Start } Programs } Cypress Server } Stop Hub.
Or
Open the Control Panel and start the Services utility. Select Cypress from the list and click the Stop the service hyperlink.
2. | Once the Hub Service is stopped, enter this command: |
db_prog start_offline_dump
Cypress will close off all data files and mark the db_prog.exe_collateral control file as being in offline dump mode.
A valid offline dump command might look like this:
c:\cypress\server\db_prog start_offline_dump
Ending Offline Dump Mode
When an offline dump completes, you must end offline dump mode.
To end offline dump mode
1. | Open a command prompt window, and set the working directory to the Cypress\Server directory. |
2. | Enter this command: |
Cypress\server\db_prog cancel_offline_dump
3. | Restart the Cypress Hub Service by taking one of these actions: |
Open a command prompt, and enter this command:
net start cypress
Or
Select Start } Programs } Cypress Server } Start Hub.
Or
Open the Control Panel, and start the Services utility. Select Cypress from the list, and click the Start the servicehyperlink.
Performing an Online Backup
In contrast to an offline DocuVault backup, the online DocuVault backup utility, or online dump mode, prepares the Cypress DocuVault for backup, while allowing continued access to Cypress features and functions by all users. The online backup employs a technique that allows data files to be frozen for backup without stopping the Cypress Hub Service.
To support online backups, Cypress employs a shadow file to which all DocuVault transactions are recorded once the DocuVault is placed in an online dump mode. The shadow file essentially acts as a temporary DocuVault data file during the online backup process. After the online backup has completed, Cypress gradually applies to the data files the changes recorded in the shadow file. After the data files are fully updated, normal operation resumes. Cypress log files continue to be updated normally, with all transactions that occur during the online backup process.
The general time line for the online backup is illustrated and described in this figure.
• | Normal Operation. Cypress is running as normal. |
• | Request Online Backup. Your backup software issues a request to Cypress to perform an online backup. Note, however, that the DocuVault is not immediately placed in online dump mode. |
• | Transition to Online Backup. Before the backup can begin, all open transactions (e.g., printing) must complete. As a result, Cypress holds requests for new transactions until those in progress are finished. Based on the number and size of the current transactions, users wanting access to certain Cypress features (e.g., printing, indexing, and other features that are recorded in the DocuVault) might experience a delay until the current transactions complete. However, requests to search and retrieve documents, launch documents from e-mail notification, etc. will complete without delay. |
When all current transactions have completed, the cache is flushed to the data files. This process results in updating the data files so that they represent a snapshot of the DocuVault.
The extent to which Cypress can delay the online backup process depends on the number of open transactions and their complexity. For example, in the event of a 50,000-page report being indexed and printed when the online backup command is issued, Cypress holds incoming transactions, but monitors the time the current transactions are taking to complete. If they are not completed within a brief period, Cypress resumes processing all transactions as normal, periodically checking to determine when the lengthy transaction completes. Once it has completed, Cypress then attempts to begin the online backup process.
• | Enter Online Dump Mode. After all current transactions have completed and the data files have been updated, the DocuVault is considered to be in online dump mode. At this time, the online_dump start command completes with an exit code of zero, triggering your backup software to begin backing up the data files in the specified directory. This is the only time it is appropriate for your backup software to copy the Cypress data files. Any held DocuVault transactions are resumed and all transactions are recorded to the shadow file. There are no delays or performance issues when transactions are being written to the shadow file versus to normal data files. |
• | Exit Online Dump Mode. When the backup software has finished, it sends a command to Cypress indicating that the backup has completed. The contents of the shadow file are used to update the data files so they reflect all transactions that occurred after the DocuVault was placed in online dump mode. During this time, you might notice an increase in CPU usage and I/O activity, but should not experience any performance issues. |
• | Transition to Normal Operation. After the data files have been updated with the shadow file data, the DocuVault is marked as clean, and a message is written to the db_prog window stating that the online backup has completed. At this time, the shadow file is automatically deleted and normal DocuVault operation resumes. |
Placing a Running DocuVault in Online Dump Mode
Make sure that you have adequate disk space before you begin the online backup. You must have enough space to hold all shadow file contents generated during the online backup. A specific value cannot be suggested because you must base this value on a variety of site-specific factors. ASG does recommend, however, that you monitor the maximum size of the shadow file created during online backups and allocate at least twice that amount of disk space for subsequent online backups.
Performing an online backup is very straightforward and simple to configure using your site’s backup software product. However, you should observe these cautions:
• | Perform online backups during periods of minimal print loads. |
• | Avoid abruptly stopping the Cypress Hub Service during an online backup. |
• | Make sure the location of the shadow directory has ample disk space and is commensurate with your load levels. The actual amount of space needed is highly site-specific. Space requirements are influenced by the length of time the DocuVault is in online dump mode, and the Cypress activity level during the backup process. |
• | Create the shadow file on a Redundant Array of Independent Disks (RAID) volume, if possible, to guard against data loss in the event of a system failure. |
To place a currently running local DocuVault in online dump mode
> | Open a command prompt window, and enter this command: |
online_dump start <directory path>
where <directory path> is the fully qualified path to the shadow directory.
When you issue this command, Cypress will begin the transition process to place the DocuVault in online dump mode and move all log files to the collected directory for backup.
When an online dump completes, you must end online dump mode.
Examples of Valid online_dump Commands
Although you can enter the online_dump command directly from a command prompt window, you also can enter it in the Before Step portion of your site’s backup software routine. If you include the command in your backup routine, you must include the complete path to the Cypress\Server directory and check the return code (errorlevel) for a successful status of zero.
Example 1. A valid online_dump command might look like this:
c:\cypress\server\online_dump.exe start c:\cypress\online_dump
To put a currently running DocuVault in online dump mode from another machine, you must add a second parameter specifying the name of the DocuVault to be backed up:
online_dump start <directory path> <DV Name>
where <DV Name> is the name/address of the DocuVault that you want to back up in the form <DocuVault name>@<IP address or DNS name>.
Example 2. A valid online_dump command from a remote machine might look like this:
Z:\Cypress\server\online_dump.exe start
Z:\abc_online_dump CompanyABC@cypress1
Auto-cancelling an Online Dump
As a normal part of the online backup operation, the Cypress DocuVault is placed in online dump mode. You can do this manually or include the command in a pre-backup step in an automated backup script. Similarly, at the end of a successful backup, you must return the DocuVault to normal operation by canceling the online dump mode. You also can perform this task manually or include the command as part of a post-backup step in the automated backup scripts.
You can configure a parameter in the Administration Tools module to instruct Cypress to automatically cancel online dump mode at a specified number of hours after placing the DocuVault in online dump mode.
To set the auto-cancel online dump parameter
1. | Open the Administration Tools module, and select the Parameter tab. |
2. | Select the Retention tab. |
3. | In the Auto-cancel online dump after (hours) field, enter the number of hours after which you wish to cancel online dump mode. Alternatively, if you want to prevent Cypress from canceling online dump mode automatically, select the Never option. |
Stopping an Online Backup
To stop an online backup in progress
> | Enter this command from a command prompt window: |
online_dump stop
You must issue this command from the Cypress\Server directory or include the fully qualified path to this directory in the command. You can issue this command only if the DocuVault is running and in online dump mode.
When Cypress receives this command, it will cease writing transactions to the shadow file and begin the process of applying the contents of the shadow file to the data files.
If the DocuVault is down for some reason and you want to take it out of online dump mode, you can enter the db_prog cancel_offline_dump command. This command will merge the pending changes from the shadow files back into the DocuVault and then perform DocuVault recovery.
Recovering Your DocuVault from an Online Backup
In the event that you need to recover your DocuVault from an online backup, this section provides steps that you can perform, including rebuilding it using your log files. If necessary, contact ASG Customer Support to assist you with these steps.
To recover the DocuVault from an online backup
1. | If DocuVault files exist from a previous or corrupted DocuVault, move or delete the files located in Cypress\Server\db_prog.exe_collateral. |
2. | Perform a restore or copy of your DocuVault backup to the Cypress\Server\db_prog.exe_collateral folder. |
3. | Open a command prompt window on the Cypress Server, navigate to the Cypress\Server folder and execute this command: |
db_prog display_db_status
This command will output the status of the DocuVault, as shown in this example:
• | The Current Database Status should be online dumping clean. |
• | If the status is offline dumping, then offline backups are being performed, but you can proceed with the steps described in Ending Offline Dump Mode. |
• | If the status is anything other than the statuses mentioned, contact ASG Cypress Support for assistance |
4. | From the command prompt, execute this command: |
db_prog restore_from_online_dump
5. | At this point, you can start Cypress, which will be at the state when online dump mode started. |
Or
You can perform a restore to apply changes (from the log files) that occurred since the online dump.
To restore from the logs
1. | Document the start log file sequence number for rebuilding and ensure that this and subsequent log files are available in the Cypress\Logs\db_prog.exe_collateral folder. |
A DocuVault can be rebuilt from the starting log file to your most recent log file available provided all of the sequentially numbered log files exist in the Cypress\Logs\db_prog.exe_collateral folder.
You may need to restore Log files from backup or move them from the other Cypress\Logs folders to the Cypress\Logs\db_prog.exe_collateral folder in order to perform the rebuild.
2. | Return to the command prompt window, and execute this command: |
db_prog rebuild_through_log <NNNNNN>
where <NNNNNN> is the value of the most recent available log file.
3. | When the command prompt returns and, if no errors are encountered, execute this command, and verify that the Current Database Status is clean: |
db_prog display_db_status
4. | Start the Cypress Hub Service. |
Performing a Log File Backup
These instructions assume that you are using a software product specifically designed to back up files to tape or other peripheral device. ASG strongly encourages you to use a backup product as it allows you to back up automatically the Cypress DocuVault at specific intervals and, once configured correctly, can protect you from operator error.
These instructions might not exactly match the steps required by your particular backup software product. For example, your product might use different names for each step, or have more or fewer steps. You should, however, still be able to map the exact commands to the appropriate steps in your backup product. Contact ASG Customer Support if you have any questions.
To run a log file backup
1. | Create a new backup job, and provide a jobname that indicates the backup is a Cypress log file backup. |
2. | Add this instruction to the Before Step of the new backup script: |
cypress\server\db_prog.exe collect_finished_logs
This instruction moves all log files from the db_prog.exe_finished directory to the db_prog.exe_collected directory. In addition, this ensures that only inactive log files are available for backup from the Cypress\Logs\db_prog.exe_collected directory and that all active log files are created or located in the Cypress\Logs
\db_prog.exe_collateral, temporary, or finished folders, which must not be backed up.
c:\cypress\server\db_prog.exe -collect_finished_logs
if %ERRORLEVEL% NEQ 0 goto mark_dump_failed
...
:mark_dump_failed
rem do whatever is needed to log a failure
3. | In the Backup Step, enter the directory path for the location of the log files to be archived: cypress\logs\db_prog.exe_collected\* Make certain that you specify the db_prog.exe_collected directory. Backing up a different directory can result in an incomplete or failed backup and possibly DocuVault errors, which can cause down time. |
4. | In the Remove Step, enter the same directory path that you entered in step 3: cypress\logs\db_prog.exe_collected\* Perform any other required steps to complete the job definition (e.g., defining scheduling requirements, etc.), then save the job. Your software will back up the DocuVault log files according to the schedule you have defined. |
Performing an Offline Resource Backup
The offline resource backup utility, or offline resource backup, allows you to back up the DocuVault without processing document-related information. This reduces the size of the backup and provides you with the capability to restore an empty DocuVault from a resource backup in a few minutes. An offline resource backup enables you to quickly have a DocuVault up and running at your remote DR site.
You must ensure these requirements are met before performing the backup:
• | The logon user must be an administrator or a power user. |
• | The database status must be clean, dirty, offline dumping, or online dumping. |
• | The copy directory must be empty. |
• | Both the resource DocuVault and the DocuVault on the DR machine must share the same license file. |
• | Both the resource DocuVault and the DocuVault on the DR machine must be in the same domain. |
To create an offline resource backup of a DocuVault
1. | Stop the Hub Service by taking one of these actions: |
Open a command prompt, and enter this command:
hub_service stop
Or
Select Start } All Programs } Cypress } Stop Cypress.
2. | Once the Hub Service is stopped, enter this command: |
db_prog offline_resource_backup copy_dir=<file_path>
where <file_path> is the path to the directory where you want all backup files stored.
For example:
db_prog offline_resource_backup copy_dir=<C:\Cypress\backup>
The command creates a sub-folder named db_prog.exe_collateral.
3. | Restart the Cypress Hub Service by taking one of these actions: |
Open a command prompt, and enter this command:
net start cypress
Or
Select Start } All Programs } Cypress } Start Cypress.
To restore an empty DocuVault from a resource backup
1. | Verify that Cypress is installed on the DR machine before you restore your DocuVault from the resource backup. |
2. | Stop the Hub Service by taking one of these actions: |
Open a command prompt, and enter this command:
hub_service stop
Or
Select Start } All Programs } Cypress } Stop Cypress.
3. | Delete the existing Cypress/db_prog.exe_collateral folder. |
4. | Copy the db_prog.exe_collateral folder from the copy_dir file path specified in step 2. to your Cypress directory. |
5. | From a command prompt, enter this command: |
db_prog display_db_status
The current status of the DocuVault is displayed on the db_prog window.
6. | Verify these parameters: |
• | The current database status is resource backup. |
• | The current log file path is valid. |
If the path is not valid, use the db_prog update command to change the log file path. See Managing DocuVault Tablesfor more information.
7. | From a command prompt, enter this command: |
db_prog restore_from_resource_backup
8. | Restart the Cypress Hub Service by taking one of these actions: |
Open a command prompt, and enter this command:
net start cypress
Or
Select Start } All Programs } Cypress } Start Cypress.
Managing DocuVault Crises
Depending on the severity of a system failure, Cypress will either recover automatically or require you to perform one or more procedures.
Automatically Recovering from System Failure
System failures can result from many different causes, including software, hardware, and human error. System failures affecting Cypress can result from improper termination of the Cypress Hub Service, overwritten or corrupted Cypress files, or other situations that introduce the possibility of data loss in the DocuVault.
To guard against loss of data, Cypress continually writes all output transactions to a log file. The collection of log files creates an audit trail that Cypress can use to rebuild the DocuVault up to the point of failure. In the event, however, that Cypress files have been corrupted or hardware has failed, Cypress will not be able to recover automatically. In this case, you will need to rebuild the Cypress DocuVault manually.
Manually Rebuilding the DocuVault
You can rebuild the DocuVault by reloading the last full backup (i.e., control file and data files) and all subsequent log file backups in their original directories. If, however, any log files are damaged, unreadable, or missing, you can restore the DocuVault only up to the last usable log file.
These are the most common ways to resolve a corrupted DocuVault: repair your table, rebuild through logs, and load your backup.
• | Repair your table. If you can recover your DocuVault from a dirty status, using the repair_dv or repair_table command may fix the problem. See Repairing a DocuVaultfor more information. |
• | Rebuild through logs. If you cannot recover your DocuVault from a dirty status or the corrupted file data is essential, using your backup and rebuilding from your log files may fix the problem. See To manually rebuild the DocuVault for more information. |
• | Load backup. If your rebuild failed due to bad or missing log files, load your latest backup. See Recovering Your DocuVault from an Online Backupfor more information. |
To manually rebuild the DocuVault
1. | Because Cypress cannot be running when you are trying to rebuild the DocuVault, terminate the Cypress Hub Service before beginning recovery. |
Select Start}Programs}Cypress Server}Stop Hubfrom the Windows taskbar.
Or
Double-click the Hub_stop icon in the Cypress program folder.
Or
Stop the hub from the Services dialog accessible from the Windows control panel.
2. | Copy the existing DocuVault server and log directories to another directory or peripheral device before attempting to rebuild the DocuVault. |
This step is a precaution in case an error occurs during the rebuild. For example, copy all files in the directory Cypress\server and Cypress\logs to a temporary directory on disk or to an attached storage device.
3. | Delete the contents of the Cypress\server\db_prog.exe_collateral directory. It must be empty before you attempt to rebuild the DocuVault. |
4. | Locate the most recent full backup and all subsequent log file backups. To rebuild the DocuVault, you must have the most recent backup of the control file and data files, plus any log files that have been created and backed up subsequent to the most recent full backup. |
The control file name is control_file.cdb. Data file names are in the format datafileXXXXXX.cdb, where XXXXXX is the numeric sequence of the data file.
This step also will augment the existing log files with log files that were backed up subsequent to the last full backup and place them in the Cypress\logs\db_prog.exe_collected directory.
In the event that you do not have enough disk space to restore all log files at once, upload as many files as space permits. Be sure to load the oldest files first and maintain the numeric sequence of the file names. Do not load log files out of sequence. For example, this list of log files is in chronological order and maintains the numeric sequence in which they were written:
• | log_file000004.cdb |
• | log_file000005.cdb |
• | log_file000006.cdb |
• | log_file000007.cdb |
• | log_file000008.cdb |
During the rebuild process, Cypress will display a missing file message when it is ready for the first log file yet to be reloaded to disk. When this message displays, delete the log files you just restored, upload as many new log files as space permits (oldest files first, and in sequence), and click the Retry button.
Repeat steps 2 through 5 until the rebuild process has completed.
6. | Identify the most recent log file so Cypress can update the data files with all log information recorded since the last full data file update. If you suspect, however, that the most recent log file might be corrupt, stop at an earlier log file. |
7. | Rebuild the DocuVault. Open a command prompt window, if not already open, and change the directory to the Cypress Server directory. |
Then issue the rebuild command:
db_prog rebuild_through_log <most-recent log #>
where <most-recent log #> is the number of the most recent log file.
For example, if the most recent log file is 000047, your rebuild command would look like this:
db_prog rebuild_through_log 47
8. | Restart Cypress as a Windows service. |
Select Start}Programs}Cypress Server}Start Hub from the Windows taskbar.
Or
Start the hub from the Services dialog accessible from the Windows control panel.
9. | If step 7. completes without error, delete the restored log files created in step 5. (in the collected directory). |
If you do not encounter any errors, your DocuVault has been restored. You can now delete the backup files that you created in step 2. .
Restoring the DocuVault
If you are not able to rebuild the DocuVault using the log files, you can restore the last-saved full backup.
To restore your DocuVault backup
1. | Locate the most recent full backup. |
2. | Because Cypress cannot be running when you are trying to restore the DocuVault, you must terminate the Cypress Hub Service before beginning recovery. |
Select Start }Programs}Cypress Server}Stop Hub from the Windows taskbar.
Or
Double-click the Hub_stop icon in the Cypress program folder.
Or
Stop the hub from the Services dialog accessible from the Windows control panel.
3. | Copy the contents of the Cypress\server\db_prog.exe_collateral directory to another directory or peripheral device. |
4. | Delete all files in the directory. It must be empty before attempting to rebuild the DocuVault. |
5. | Delete the contents of these directories: |
• | Cypress\logs\db_prog.exe_collateral |
• | Cypress\logs\db_prog.exe_collected |
• | Cypress\logs\db_prog.exe_finished |
6. | Restore the most recent full backup to Cypress using your backup software product. This step will replace the existing control file and data files with the last-saved full backup to the Cypress\server\db_prog.exe_collateral directory. |
The control file name is control_file.cdb. Data file names are in the format datafileXXXXXX.cdb, where XXXXXX is the numeric sequence of the data file.
7. | If the full backup was made correctly, the restored database will currently be marked as being in dump mode. Change it to ready for use. |
Then issue this command:
Cypress\server\db_prog.exe cancel_offline_dump
If you encounter an error and a screen displays, it most likely means that the DocuVault was not stopped when the full backup was performed. In this event, the backup is corrupt and you do not have the ability to restore your DocuVault from your backup file.
8. | Restart Cypress as a Windows service. |