Académique Documents
Professionnel Documents
Culture Documents
Cach System Administration Guide Cach Version 5.0.17 30 June 2005 Copyright 2005 InterSystems Corporation. All rights reserved. This book was assembled and formatted in Adobe Page Description Format (PDF) using tools and information from the following sources: Sun Microsystems, RenderX, Inc., Adobe Systems, and the World Wide Web Consortium at www.w3c.org. The primary document development tools were special-purpose XML-processing applications built by InterSystems using Cach and Java.
The Cach product and its logos are trademarks of InterSystems Corporation.
The Ensemble product and its logos are trademarks of InterSystems Corporation.
The InterSystems name and logo are trademarks of InterSystems Corporation. This document contains trade secret and confidential information which is the property of InterSystems Corporation, One Memorial Drive, Cambridge, MA 02142, or its affiliates, and is furnished for the sole purpose of the operation and maintenance of the products of InterSystems Corporation. No part of this publication is to be used for any other purpose, and this publication is not to be reproduced, copied, disclosed, transmitted, stored in a retrieval system or translated into any human or computer language, in any form, by any means, in whole or in part, without the express prior written consent of InterSystems Corporation. The copying, use and disposition of this document and the software programs described herein is prohibited except to the limited extent set forth in the standard software license agreement(s) of InterSystems Corporation covering such programs and related documentation. InterSystems Corporation makes no representations and warranties concerning such software programs other than those set forth in such standard software license agreement(s). In addition, the liability of InterSystems Corporation for any losses or damages relating to or arising out of the use of such software programs is limited in the manner set forth in such standard software license agreement(s). THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BY INTERSYSTEMS CORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTER SOFTWARE. FOR COMPLETE INFORMATION REFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARE LICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION, COPIES OF WHICH WILL BE MADE AVAILABLE UPON REQUEST. InterSystems Corporation disclaims responsibility for errors which may appear in this document, and it reserves the right, in its sole discretion and without notice, to make substitutions and modifications in the products and practices described in this document. Cach, InterSystems Cach, Cach SQL, Cach ObjectScript, Cach Object, Ensemble, InterSystems Ensemble, Ensemble Object, and Ensemble Production are trademarks of InterSystems Corporation. All other brand or product names used herein are trademarks or registered trademarks of their respective companies or organizations. For Support questions about any InterSystems products, contact: InterSystems Worldwide Customer Support Tel: +1 617 621-0700 Fax: +1 617 374-9391 Email: support@InterSystems.com
Table of Contents
1 Introduction ..................................................................................................................... 1 2 Using Cach on Windows ................................................................................................ 3 2.1 Cach Cube .............................................................................................................. 3 2.2 Starting Cach .......................................................................................................... 5 2.3 Stopping Cach ........................................................................................................ 6 2.4 Controlling Cach from the Command Prompt ....................................................... 7 3 Using Cach on Linux and UNIX ................................................................................... 9 3.1 Starting Cach .......................................................................................................... 9 3.2 Stopping Cach ...................................................................................................... 10 4 Using Cach on OpenVMS ........................................................................................... 13 4.1 Starting Cach ........................................................................................................ 13 4.2 Stopping Cach ...................................................................................................... 14 5 Using Multiple Instances of Cach ............................................................................... 15 5.1 Cach Instances ...................................................................................................... 15 5.2 Connecting to a Cach Instance ............................................................................. 16 5.3 Controlling Cach Instances .................................................................................. 17 5.4 Configuring Multiple Cach Instances .................................................................. 18 5.4.1 Set Port Numbers .......................................................................................... 19 6 Connecting to Remote Servers ..................................................................................... 21 6.1 Define a Remote Server Connection ...................................................................... 22 7 Configuring Cach ......................................................................................................... 23 7.1 Configuring System Information ........................................................................... 23 7.2 Configuring Databases ........................................................................................... 24 7.3 Configuring Namespaces ....................................................................................... 27 7.3.1 Create a Namespace ..................................................................................... 28 7.3.2 Change a Namespace Name ......................................................................... 28 7.3.3 Modify Database Mapping ........................................................................... 29 7.3.4 Add Global and Routine Mapping to a Namespace ..................................... 30 7.3.5 Change the Size of the Namespace Table ..................................................... 32 7.4 Configuring License Managers .............................................................................. 32 8 Managing Cach ............................................................................................................ 35
8.1 Controlling Cach Processes .................................................................................. 35 8.1.1 Display Process Information ........................................................................ 36 8.1.2 Display Process Details ................................................................................ 39 8.1.3 Stopping a Process ........................................................................................ 40 8.1.4 Debug a Process ........................................................................................... 41 8.1.5 Broadcast Messages to Terminals ................................................................ 41 8.2 Monitoring Local Databases .................................................................................. 42 8.3 Monitoring Locks ................................................................................................... 43 8.4 Monitoring Log Files ............................................................................................. 45 9 Achieving High Availability .......................................................................................... 47 9.1 Surviving a Crash ................................................................................................... 48 9.1.1 Write Image Journaling ................................................................................ 48 9.2 Backup Strategy ..................................................................................................... 49 9.2.1 Concurrent External Backup ........................................................................ 50 9.2.2 Non-Concurrent External Backup ................................................................ 50 9.2.3 Concurrent Cach Backup ............................................................................ 51 9.2.4 Cold Backup ................................................................................................. 51 9.3 Logical Data Protection ......................................................................................... 52 9.3.1 Transaction Processing ................................................................................. 52 9.3.2 Transactions and Locking ............................................................................. 53 9.3.3 Global Journaling ......................................................................................... 54 9.4 Database Integrity Protection ................................................................................. 55 9.4.1 Database Integrity Checking ........................................................................ 56 9.4.2 Database Integrity Checking Utility ............................................................. 57 9.5 Shadow Journaling ................................................................................................. 57 9.6 System Failover Strategies ..................................................................................... 58
List of Figures
Cach Cube Menu ................................................................................................................ 4 Sample Namespace Mapping ............................................................................................. 31
List of Tables
Cach Cube Commands ....................................................................................................... 4 Control Commands ............................................................................................................. 16 Cach csession Command and Arguments ......................................................................... 16 Cach ccontrol Command and Functions ........................................................................... 17 Add Connection Input Fields .............................................................................................. 22 Control Panel Functions ..................................................................................................... 36 Process Column Information .............................................................................................. 37 Possible Process States ....................................................................................................... 38 Local Databases Information .............................................................................................. 43 Lock Table Information ...................................................................................................... 44 Failover Strategy Impact ..................................................................................................... 59
1
Introduction
This book is an introduction to accessing and running a Cach system. Managing Cach is easy; whether running on a single PC or on a system of thousands of users, most of the information you need to get the system running is contained in this document. Cach is available on a number of different operating systems. Certain administrative procedures and tasks may differ according to platform. Where this is the case, this document describes these differences. Cach offers many different ways to perform system administration. On Microsoft Windows systems, Cach provides a complete set of graphical user interface (GUI) system utilities (available from either the Cach Cube in the Windows system tray or from the Cach submenu of the Windows Programs menu). These graphical utilities are client/server applications that can talk to the local Cach system or a remote Cach server regardless of platform. In addition, Cach provides a set of analogous, text-based utilities that can be invoked from the Cach Terminal or used to manage a remote system using Telnet. This book introduces the following topics: Using Cach on Windows Using Cach on Linux and UNIX Using Cach on OpenVMS Using Multiple Instances of Cach Connecting to Remote Servers Configuring Cach Managing Cach
Introduction
2
Using Cach on Windows
The primary Cach interface is the Cach Cube. From the Cach Cube, you can start all of the Cach configuration and management tools. You can also invoke each Cube command from a shortcut or command line. Correspondingly, you can initiate many of the Cach tools from the Windows Start menu by pointing to Programs, Cach, and then to the appropriate Cach configuration name.
When you click on the Cach Cube, a menu appears with commands to use the Cach utilities and programming environments.
You can only use the Cach Cube menu from Windows. The Cach Cube provides a simple interface to the Cach tools used to control and configure your Cach systems. The following commands are available from the Cach Cube menu: Cach Cube Commands
Cach Cube Command
Getting Started Start Cach
Function Displays tutorials, release notes, and documentation. Starts the default configuration specified in the square brackets after the menu item, for example [CACHE]. If the Cach server is already started, this option appears dimmedit is unavailable. Shuts down or restarts the local Cach configuration. Creates, edits, deletes, and compiles Cach class definitions, CSP (Cach Server Pages) pages, Cach Basic routines, and Cach ObjectScript routines. See Using Cach Studio. Invokes the command line interpreter in the Cach programming environment.
Terminal
Starting Cach
Function Displays classes, globals, and routines, and functions for managing each. Displays tables and views, perform queries and SQL management functions. See Using Cach SQL Manager. Performs common system management tasks. See Managing Cach. Creates databases and namespaces, and adjusts all Cach configuration settings. See Configuring Cach. Displays Cach online documentation. Displays a submenu of all the Cach utilities with access to any defined remote Cach server. The Cach Telnet command starts the Cach terminal emulator and allows you to choose your host from within the Telnet window. Shows a list of remote servers and maintains server connections by using the Add/Edit command on the submenu. The preferred server has a check mark next to it. Displays Cach version and build information. Removes the Cach Cube icon from the system tray; this does not stop Cach.
SQL Manager
Control Panel
Configuration Manager
Preferred Server
[Server
name]
About Exit
access the Bin folder in the Cach configuration directory (CacheSys by default) and doubleclick the csystray.exe file. Alternatively, you can enter these commands from the <cache-install-dir>/bin directory in the Open box of the Run item on the Windows Start menu. For example, to start the configuration named cache, enter the following command and click OK.
See Controlling Cach Instances for more options and information on the ccontrol command.
3
Using Cach on Linux and UNIX
This chapter describes the specific procedures on Linux and UNIX: Starting Cach Stopping Cach
where configname is the name of the configuration you want to start. See Controlling Cach Instances for more options and information.
To stop Cach, from the command line: 1. Use the ccontrol command:
ccontrol stop <configname>
where configname is the name of the configuration you want to stop. See Controlling Cach Instances for more options and information. 2. This procedure invokes the Cach SHUTDOWN utility, which displays a status report. Check for active processes in the report to determine if the next step is necessary. 3. Should it be necessary, broadcast a message to any users on the system:
Do you want to broadcast a message to anyone? No=> Yes Send a message to other terminals. Message => Please sign off Terminal => /dev/tty/06 Terminal => Message =>
4. After sending one message you can send others, until you respond to the Message prompt by pressing Enter. 5. When the system asks if you would like to see another system status, enter Yes to see one, or press Enter if you do not want another report.
Stopping Cach
6. If you answer Yes, when the system status displays again, identify any active terminals. 7. Confirm that you want to halt by answering Yes. If you answer No, the shutdown procedure quits and Cach continues running.
4
Using Cach on OpenVMS
This chapter describes the following procedures on OpenVMS: Starting Cach Stopping Cach
Run the Cach startup procedure. The distribution includes a template of this startup command procedure, CACHE$STARTUP.COM; modify this file as necessary for your site. Run CACHE$STARTUP.COM at the operating system level when you restart OpenVMS, as well as when you install or upgrade Cach. To start Cach, modify the CACHE$STARTUP.COM file to automatically start the desired Cach configuration when OpenVMS starts (as described in the header text of the file.) You can also start Cach from the command line, using the ccontrol command as follows:
where configname is the configuration name that you chose during the installation. See Controlling Cach Instances for more options and information.
where configname is the name of the configuration that you want to stop. See Controlling Cach Instances for more options and information. 2. This procedure displays a status report. Check for active processes in the report. 3. If there are active users on the system, you should send them a warning message that you are about to shut down the Cach system. Enter the message you want to send, and the terminal to which you want to send it. To send a message to several terminals, specify each terminal individually. For instance:
Do you want to broadcast a message to anyone? No=>Yes Send a message to other terminals. Message => Please sign off Terminal => _NTY5: Terminal => <RETURN> Message =>
4. When the system asks if you would like to see another system status, enter Yes to see one, or press RETURN if you do not want another report. 5. Confirm that you want to halt by answering Yes. If you answer No, the shutdown procedure quits, and Cach continues running.
5
Using Multiple Instances of Cach
You are not limited to running only one Cach system on a machine. You can install multiple Cach systems; each has its own Cach Cube. These environments are referred to as Cach instances. An instance is a unique independent Cach environment. This chapter addresses the following topics: Cach Instances Connecting to a Cach Instance Controlling Cach Instances Configuring Multiple Cach Instances
To control a Cach instance from the command line, use the configuration name. The following table shows the most common commands to manipulate Cach instances. Control Commands
Action desired Starting a Cach instance Connecting to a Cach instance Stopping a Cach instance Cach command ccontrol start <configname> csession <configname> ccontrol stop <configname>
From the Cach Cube, you can also control multiple remote Cach environments. Cach allows you to create and edit all Cach data on remote systems. This includes, but is not limited to, running remote backups, editing remote configurations, and creating and compiling remote objects and routines. See the chapter on Connecting to Remote Servers for more detailed information.
Where configname is the configuration name that you chose during the installation. Cach csession Command and Arguments
Command csession <configname> -"B" Description Provides system administrator login to perform system tasks such as setting up licensing. Specifies the login namespace. Runs a routine in user mode.
To use application mode or the Cach command line on a remote server use a Telnet client, LAT terminal, or the Cach Terminal.
* Functions for OpenVMS only. In the table above, configname is the name of the configuration that you are managing and configfile is an optional alternate configuration file (with a .cpf extension) that is located in the same directory as the configuration being started. If you do not include a configuration name, or the configuration you specify does not exist (that is, there is no .cpf file of that name), then Cach activates your default startup configuration (usually cache.cpf). The optional arguments (indicated by [args]) available are: quietly non-interactive with minimal dialog nostu do not run the startup routine (^STU)
help print the help message and exit restart start Cach after a successful shutdown (for stop function only and not available on Microsoft Windows platforms)
Any other value is taken as a .cpf configuration file name You may have your own procedures that involve using the scripts cstart and cstop, among others. Cach can accommodate these procedures. These scripts, in fact, are invoked by ccontrol. Invoke the ccontrol help command to obtain the most recent description of the interface with these scripts. For an example of creating user start and stop procedures, see the Use of the ^%ZSTART and ^%ZSTOP Cach Routines article.
Each instance must have unique port numbers. See the next section for information on how to Set Port Numbers. Please see the Multiple Cach Installation Issues section of the Cach Installation Guide for important facts when installing multiple instances of Cach.
Note:
Note:
If you frequently use and manage multiple instances of Cach on one machine, it may be helpful to assign unique port numbers immediately after installing. The assignment of unique port numbers ensures that the Cach default port number is always available for use by another installation and avoids confusion when using the Cach Cube tools on multiple instances from one Windows client.
6
Connecting to Remote Servers
You can control remote instances from a Telnet session or from the Remote System Access submenu on the Cach Cube. To use the utilities on the Remote System Access submenu for a remote instance: 1. Define a remote server connection to add the server to the preferred server list. 2. Click the Cach Cube and point to Remote System Access. 3. Point to a cube utility and then click the server name. You may also connect to a remote instance of Cach from a Telnet session: 1. Click the Cach Cube and point to Remote System Access. 2. Click on Cach Telnet, connect to the remote server, and log on to the Cach system with your username and password. Alternatively, if the server is on the preferred server list, point to Terminal and then click the server name. You can remotely log into a Cach instance on any supported platform from a terminal running on a PC or from any workstation client capable of running Telnet. This client could possibly have only utilities (for the system management of servers) and not a Cach instance. The version of Cach on the client PC in most cases, must be the same or a later version of the Cach system it manages. Note: Users of the Mac OS X platform can also use SSH from a command prompt on Windows to connect to their OS X machine.
Important:
The Cach SuperServer must be running on the remote machine and its port must be open on your firewall to use the Cube utilities on that system. For security reasons, username and password are no longer stored with the remote connection information.
7
Configuring Cach
A Cach configuration is composed of system configuration information, namespaces, databases, network connections, CSP applications, and a Cach license. Use the Cach Configuration Manager to set up a Cach system and view its configuration parameters. You can use the Configuration Manager to adjust system settings as well as to create and modify namespaces, databases, network connections, and CSP applications. Most configuration changes can be done dynamically and do not require you to restart Cach. This chapter covers the following configuration tasks: Configuring System Information Configuring Databases Configuring Namespaces Configuring License Managers
There are a variety of advanced options available; however, these topics are not critical to running most Cach systems. These advanced options are described in various Cach topicspecific guides and reference books that you can access from the documentation home page.
Configuring Cach
with the provided configuration called cache.cpf the default configuration. In most cases, this configuration file is the only one you will need to use Cach. When you first install Cach, you may change some default system information. The General tab of the Configuration Manager provides an interface to the database allocation features. There is a Details button next to the Memory for Database Cache box that you can click to display boxes for allocating the global buffer pool. You can specify how global buffer pool memory is allocated among 2-KB and 8-KB block sizes. If you are running Windows 2000/NT, you can configure Cach to start automatically: 1. Click Configuration Manager on the Cach Cube. 2. On the General tab, select the Start Cach on System Boot check box and click OK.
Configuring Databases
Cach databases dynamically expand as needed, though you can set a maximum limit. Secondary volumes of a database are called cache.ext files. The databases are automatically mounted and can grow to be 32 terabytes if you are using the default 8-KB block size. The theoretical maximum for the number of Cach databases is 15,998. However, you can only have open at one time as many as permitted by the operating system limit on maximum open files (either per process or system-wide), minus what Cach reserves for its own use and device, which is approximately half. You can make most database configuration changes dynamically; you can create, delete, or modify database attributes while the system is running. You can create new databases with an 8-KB block size; you can also create 2-KB databases for backward compatibility with versions of Cach prior to release 4.1. Cach provides a wizard for database creation. 1. Invoke this wizard from the bottom of the Configuration Manager dialog box or by clicking Add from the Databases tab:
2. In the Set Database Name dialog box, enter a database name and click Next. If you are creating a remote database, select the Database is remote check box and follow the instructions to designate the remote server name or address.
Configuring Cach
3. Select the directory where the database will reside and click Next. If the directory does not currently exist, Cach asks if you wish to create it. Click Yes.
4. Click Advanced to change the Block Size of your database from the default 8 KB to the older 2 KB. In the Initial Size box, type or select the number of megabytes for your database size.
Configuring Namespaces
5. Click Finish to add your database to the configuration file. You are now ready to further configure and manipulate your new database. Note: To protect you from accidentally corrupting a database, you cannot open or write to an operating system file called cache.dat or cache.ext, even if it is not a mounted database.
Configuring Cach
Modify Database Mapping Add Global and Routine Mapping to a Namespace Change the Size of the Namespace Table
By selecting the Define a CSP application for this Namespace check box, you create a default CSP application for this namespace. 3. When you have completed all the questions, click Finish to add your namespace to the configuration.
Configuring Namespaces
1. From the Namespaces tab, select the desired namespace, and click Change. 2. Type the new name and press Enter. 3. Click OK to update the configuration.
Configuring Cach
1. From the Namespaces tab, expand the desired namespace tree by clicking on the plus sign next to its name or by double-clicking the name. 2. Expand Default Databases. 3. Click the element that you want to redefine. 4. Click Change to bring up a list of valid databases for the element. 5. Select the new database and click OK. Note: Users directly accessing the database at the time of the change may need to log off and then log on to Cach to update their namespace mapping.
Configuring Namespaces
2. Select Global Mapping or Routine Mapping. 3. Click Add. 4. Enter the name of the Routine or Global and click OK. This creates an entry in the Global or Routine table and provides access points for you to change the global or routine mapping. To add subscript level mapping to the global: a. Select Subscript Level Mapping and click Add. b. Enter the first subscript range and click OK. c. Expand the subscript range in the list, select Data, and click Change. d. Select the database location where to map the data and click OK. e. Select Data Replication and click Add. f. Select the database on which to replicate the data and click OK.
g. Repeat these steps until you have mapped all the subscript ranges you require. The following is a schematic diagram of how mapping works in a sample airline reservation application: Sample Namespace Mapping
Data and programs are stored in Cach databases, the physical storage locations, and referred to by namespaces, the logical references.
Configuring Cach
From this tab, you may add a new license manager, remove a specific license manager, or change the address and port information of an existing license manager. A license manager is defined by the IP address of the host on which it runs and the UDP port it uses to communicate. You can enter the IP address in dotted decimal format (192.29.233.19) or in alphabetic format (mycomputer.myorg.com). The license manager port number must be a number between 1024 and 65535. InterSystems uses a default port number of 4001. Unlike the license servers used in earlier versions of Cach, the port numbers of redundant license managers running on different hosts do not need to be unique. For more information on licensing, see the technical article, Cach License Management.
8
Managing Cach
This chapter explains common Cach management tasks including displaying process details, broadcasting messages, and monitoring processes. This chapter discusses the following topics: Controlling Cach Processes Monitoring Local Databases Monitoring Locks Monitoring Log Files
In this chapter, the word process by itself refers to both user and background processes. The Cach Control Panel utility is the primary tool for monitoring and controlling processes:
Managing Cach
Stopping a process Debug a process Broadcast messages to terminals Monitoring local databases Monitoring locks Monitoring log files
* You can access the shortcut menu by right-clicking the selected process in the contents window.
You can customize the process display to show only the information that interests you. From the Control Panel: 1. On the Options menu click Process Columns. 2. Select or clear the appropriate check boxes of the items you wish to include or not to include in the contents window. 3. Click OK. The following table describes the process information available for display: Process Column Information
Column Heading
Process Device Namespace Routine Lines Executed Global References
Definition Operating system process identification number.* Current device the process is using. Namespace in which the process is running. Name of the routine that the process is currently executing. Number of lines of source code executed. Number of global references, including updates, executed (database reads and writes) since the process entered Cach. Number of code lines changed since the last update.
Managing Cach
Column Heading
Global Refs/Sec State
Definition Number of global references changed since the last update. Process state. See the Possible Process States table below for an explanation of each state. Name of the user who owns the process. Name of the client system that initiated the process. Name of the executable that called the process. IP Address of the system that initiated the process.
* An asterisk (*) appears next to the process id if the user entered Cach in programmer mode. A plus or minus sign appears next to callin processes:
+ Process is in Cach Process is not in Cach
The callin interface is a Cach SQL facility that lets you execute and evaluate Cach ObjectScript commands and expressions from within C programs. You can also use the callin interface from $ZF routines. The following table lists the possible process states as displayed in the process information table: Possible Process States
State LOCK OPEN CLOSE USE READ WRITE GGET GSET GKILL GORDER Process Performing a Cach lock. Opening a file or device. Closing a file or device. In a Use command. Reading from a file or device. Writing to a file or device. Retrieving a value from a global. Setting a value into a global. Killing a global/node. Executing $order.
State GQUERY GDEFINE ZF HANG JOB JOBEXAM BROADCAST SUSPEND GINCR GBITSET GBITGET RUN
Process Executing $query. Executing $data. Calling out from Cach. Suspended (by the Cach Hang command). Executing a process initiated by the Job command. Examining the state of another running process. Broadcasting a message to other processes. Suspended (through user interaction using JOBEXAM). Executing $increment. Setting bit strings in a global (Set $bit). Retrieving bit values from a global. Executing Cach code other than global module or I/O commands.
The following codes may be attached to the end of a state: H Halting NH Network hardening N Remote network W Hibernating
Managing Cach
Managing Cach
To broadcast a message to the terminals associated with a selected process, from the Control Panel: 1. Click the Processes task folder. 2. Right-click the process in the contents window. 3. Click Broadcast Message on the shortcut menu. 4. Enter your message in the text box. 5. Click Selected process; the process identification number (pid) of the selected process is automatically displayed in the text box. If you want to broadcast to all processes, click that option instead. 6. Click OK. An alternate way to broadcast a message to all processes is by right-clicking the Processes task folder. Then click Broadcast Message on the shortcut menu. All processes is the only available option for the destination, and is selected already. Click OK.
Monitoring Locks
Definition The database name. The system directory in which the database resides. The status of the directory, which indicates if the database is mounted. The current allocated size of the database, in bytes. The percent of the currently allocated database size that is in use. The maximum size allocated to which the database can grow. The percent of the maximum size allocated that is in use. Indicates whether the database is mounted as part of a cluster. The block size of the database. Indicates whether the database is read-only.
From this dialog box you can perform various database tasks such as creating, modifying, expanding, and deleting a Cach database. Cach provides an additional tool to monitor the storage growth of your databases. This utility is called %FREECNT. Its output shows the free space available within a database:
USER>Do ^%FREECNT # of Free blocks blocks 128 107 83.6% Free data blocks 93 72.7% Expansion available Directory *** c:\cachesys\mgr\user\
Managing Cach
In most cases, the only time you need to remove locks is as a result of an application problem. The Lock Table has the following column entries. Lock Table Information
Column Heading
Item Locked Process Exclusive
Definition The locked variable. The process ID of the process holding the lock. The lock count for the exclusive lock mode. When there is a D on the tail of the count, it means it is unlocked inside a processing transaction. The lock count for the shared lock mode. The total number of jobs that are waiting for this lock. The lock attributes.
For a more in-depth description of the Lock command and its features, see the Lock entry of the Cach ObjectScript Reference guide. You may need to enlarge the size of the lock table if your system uses a large number of locks: 1. Click the Advanced tab of the Configuration Manager. 2. Expand the Memory branch.
44 Cach System Administration Guide
3. Double-click Lock Table to display the Change Property dialog box. 4. Use the slider to specify the amount of memory allocated on your system for locks (in bytes), and click OK. The minimum is 65536; the maximum value depends on the value of Generic Memory Heap. Increase the heap size if you need more room for the lock table. Cach rounds up the value to the next multiple of 64 KB. The default range is from 655361769472. 5. Click OK on the Configuration Manager to change the configuration. Click Restart to restart Cach and put the configuration changes into immediate effect.
Managing Cach
If you have any trouble starting Cach, it is recommended that you view the console log file. The cconsole.log file grows until it reaches a maximum size, when it is renamed cconsole.old. The value is configurable (default is 5 MB) using the Cach Configuration Manager. Expand the General settings branch on the Advanced tab, and update the number of MBs for Max Console Log Size. You may also view log information about application errors and ODBC errors.
9
Achieving High Availability
This chapter provides an overview of the mechanisms that Cach provides to maintain a highly available and reliable system. It describes strategies for recovering quickly from system failures while maintaining the integrity of your data. This chapter discusses the following topics: Surviving a Crash Backup Strategy Logical Data Protection Database Integrity Protection Shadow Journaling System Failover Strategies
Cach write image journaling technology protects against internal integrity failures due to system crashes. Cach backup and journaling systems provide rapid recovery from physical integrity failures. These utilities can be used while applications are running and the database is being updated. Logical database integrity is ensured through transaction processing statements and automatic rollback. Most of these subjects are described in further detail in the Cach High Availability Guide. Important: InterSystems recommends isolating all WIJ (cache.wij), PIJ (cache.pij, cache.pijxxx), and journal (yyyymmdd.nnn) files from the database (cache.dat) files. Placing these files on a separate disk may be critical if there is a crash and the database is corrupted. It minimizes the risk of these files also being corrupted, increasing the opportunity for successful recovery.
When Cach starts, it automatically checks the write image journal and runs a recovery procedure if it detects that an abnormal shutdown occurred. When Cach indicates successful completion, the internal integrity of the database is restored. Recovery is necessary if a system crash or other major system malfunction occurs at either of the following points in the two-phase write protocol process: Before the Write daemon has completed writing the update to the write image journal. In this case, recovery discards the incomplete entry.
Backup Strategy
After the update to the write image journal is complete but before the update(s) to the database is complete. In this case, recovery rewrites the updates from the write image journal file to the database. The two-phase write protocol safeguards structural database integrity, but it does not prevent data loss. If the system failure occurs prior to a complete write of an update to the write image journal, Cach does not have all the information it needs to perform a complete update to disk. That data is lost.
Note:
You can vary these strategies based on your environment: the operating system, preferred backup utilities, disk configurations, and backup devices. For further information to help you to develop a backup strategy tailored for your environment, or to review your current backup practice, please contact the InterSystems Worldwide Response Center.
4. Copy the incremental file to the backup save-set, using your preferred UNIX command. The following is an abbreviated example of the cbackup script:
../bin/cuxs -s . -U "" -B << cleanup s x=\$\$CLRINC^DBACK("NOISY") i x s x=\$\$BACKUP^DBACK("","E","UNIX Backup via call_os_backup","","","") o "cback_temp":"WAS" u "cback_temp" w x c "cback_temp" h cleanup
Backup Strategy
processing. You back up the mirror and then later rejoin it to the production disk(s) and catch up. Cach makes it easy to integrate in this configuration: 1. Switch the journal file using the Control Panel, JRNSWTCH, or the API INT^JRNSWTCH. 2. Quiesce Cach processing in a safe way, to ensure the structural integrity of globals. Make sure that application processes pause and system processes are allowed to complete their work by setting a software switch that inhibits activity and waiting for all processes to quiesce. The API, ENQ13^DBACKA, completes both operations within a few seconds. Set the variables CLUBACKUP, ALRDY13, and NOFORCE to 0 before calling ENQ13. 3. Separate the disk mirror from production. 4. Resume Cach processing by calling the API DEQ13^DBACKA, which clears the software switch that inhibits processing. 5. Back up the mirror copy. 6. Rejoin the mirror disk(s) with production.
3. Restart Cach using the ccontrol command or through the Cach Cube.
For more information, see the Transaction Processing chapter of Using Cach ObjectScript and the Managing Transactions section in Using Multidimensional Storage.
If an operator terminates a process, Cach automatically rolls back incomplete transactions. Following an abnormal termination of the entire Cach system, as in the case of a hardware failure, rollback of all incomplete transactions occurs the next time Cach starts.
For rollback to occur, Cach stores additional information in the journal. Let's suppose that a transaction involves the transfer of $100 from a savings account with a starting balance of $1,000, to a checking account with a balance of $500. Without transaction processing, there are two journal entries:
SET SAVINGS 900 SET CHECKING 600
Now suppose that transaction processing is invoked by preceding these updates with a command to begin the transaction, and following them with a command to commit the transaction. In this case, the journal conceptually contains:
START SET SAVINGS 900 OLD SAVINGS 1000 SET CHECKING 600 OLD CHECKING 500 COMMIT
In addition to the new values of 900 and 600, the journal contains the pre-transaction values of 1000 and 500. In the event that a rollback is required before the transaction is committed, these old values are used. When a system crash occurs, rollback happens automatically. First, recovery via the twophase write protocol restores the internal consistency of the database. Next, all incomplete transactions (those that began but were never committed) are rolled back.
The value of SAVINGS becomes unavailable to other processes when it is locked, and available again as soon as it is unlocked. Now suppose that a transaction fails as the application is updating CHECKING. Transaction rollback occurs, restoring SAVINGS to its pre-transaction value. But, what if between the instant the application unlocks SAVINGS and transaction rollback completes, another process accesses SAVINGS? If it examines this value, it may carry out further processing that is erroneous. Worse yet, if it changes this value, rollback cannot occur. Cach automatically avoids this problem by deferring any unlocks within a transaction until the transaction is committed or rolled back. Within the transaction, the data appears to be unlocked, permitting a subsequent lock of the same value in the same transaction to work correctly. Outside the transaction, however, the data remains locked.
When Cach starts, all journal entries since the last Write daemon pass are reapplied. Since user processes update the journal concurrently, rather than through the Write daemon, this approach provides added assurance that updates prior to a crash are preserved. Backups and journaling are daily operations that allow you to recreate your database. If a failure renders your database inaccessible or unusable, you can restore the backups and apply the changes in the journal to recreate your database.
serve update sequence may yield a database that is internally consistent but logically invalid. The incremental backup file structures are protected, as well as the database. A valid incremental backup can thus be performed following recovery from a crash.
Shadow Journaling
2. A Display File dialog box appears. On the File menu, click Open. In the File name box, enter the name of the log file you entered in the background integrity check process, then click Open. 3. You are now able to view the log file.
checking.
Do Silent^Integrity(logfilename) starts a background job which does an integrity
check on all databases and puts the output in a file specified by the logfilename parameter. This is the equivalent of doing Background Integrity Check from the Control Panel.
Do Query^Integrity(logfilename,outdevice) does not run an integrity check, but
puts the contents of the file specified by the logfilename parameter, the results saved from a previous run, out on the current device or the device specified in the optional parameter outdevice. If not specified, outdevice is the current terminal. Examples of outdevice are a printer, another display device, or another OS filename. The latter makes a copy of logfilename.
information from the primary machine to the secondary machine, shadow journaling makes it possible to fail over to a database which is within only a few transactions of the primary database. By itself, shadow journaling does not ensure successful failover, but it is a very simple and inexpensive way to maintain a disaster recovery system. Often, this approach is also used to update a report server, where ad hoc reporting tasks can operate on current data without affecting production. Shadow journaling monitors database activity on a primary system and causes the same activity to occur on a secondary system. It does this by means of a shadow client service running on the secondary system that continually requests journal file details from a shadow server service running on the primary system. The shadow server service responds by sending the details of the Set or Kill journal record entry to the secondary system over a TCP connection. For more detailed information, see the Shadow Journaling chapter of the Cach High Availability Guide.
Each of these approaches is described in greater detail in the System Failover Strategies chapter of the Cach High Availability Guide. Variations on these strategies are also available. For further information to help you develop a failover and backup strategy tailored for your environment, or to review your current backup practice, please contact the InterSystems Worldwide Response Center.