Vous êtes sur la page 1sur 66

Cach System Administration Guide

Version 5.0.17 30 June 2005

InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com

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

Cach System Administration Guide iii

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

iv Cach System Administration Guide

List of Figures
Cach Cube Menu ................................................................................................................ 4 Sample Namespace Mapping ............................................................................................. 31

Cach System Administration Guide v

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

vi Cach System Administration Guide

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

Cach System Administration Guide 1

Introduction

Achieving High Availability

2 Cach System Administration Guide

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.

2.1 Cach Cube


When you start Cach on a Windows-based system, the Cach Cube tray of the taskbar. appears in the system

When you click on the Cach Cube, a menu appears with commands to use the Cach utilities and programming environments.

Cach System Administration Guide 3

Using Cach on Windows

Cach Cube Menu

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.

Stop Cach Studio

Terminal

4 Cach System Administration Guide

Starting Cach

Cach Cube Command


Explorer

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

Documentation Remote System Access

Preferred Server

[Server

name]
About Exit

2.2 Starting Cach


To start Cach, run the startup procedure at the system level. This procedure activates either a default configuration or a configuration you specify. If you have any trouble starting Cach, view the console log using the Control Panel as described in the Monitoring Log Files section of the chapter on Managing Cach. To start Cach on the Windows platform, select Start Cach from the Cach Cube. This starts the Cach system specified as the default configuration. When Cach is not running, the Cach Cube icon appears dimmed. If the Cach Cube is not in the system tray, from the Start menu point to Programs, Cach, the Cach configuration name, and click Start Cach. To return the Cube to the system tray,

Cach System Administration Guide 5

Using Cach on Windows

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.

2.3 Stopping Cach


Normally you leave your Cach system running. However, if your operating system requires a restart, stop Cach before you shut down your system. The Cach maintenance tasks, such as backups and database repair utilities, do not require you to stop Cach. From the Cach Cube menu click Stop Cach to shut down or restart the local Cach configuration. By default, this option shuts down (or restarts) Cach immediately, using the default shutdown routine. However, it also provides options for setting a timer for a delayed shutdown, for running a user-defined shutdown routine, and for broadcasting a warning message to users on the server. InterSystems recommends that you use Stop Cach to shut down Cach to ensure that it closes properly. Note: You cannot cancel a shutdown once the countdown reaches 0 and the shutdown procedures have started.

6 Cach System Administration Guide

Controlling Cach from the Command Prompt

2.4 Controlling Cach from the Command Prompt


You can also control a Cach configuration from the Windows command prompt by running the css.exe program in the <cache-install-dir>\Bin directory.
Command css start <configname> css stop <configname> css stopnoshut <configname> css stopstart <configname> css force <configname> css [run | console | cterminal] <configname> css [run | console | cterminal] <configname> <routine> css [run | console | cterminal] <configname> <routine> <namespace> Description Starts the specified configuration. Shuts down the named configuration. Shuts down the named configuration using INTNOSHUT^SHUTDOWN. Shuts down and restarts the named configuration. Forces down the named configuration. Runs Cach in programmer mode with either no device, the console, or the terminal for $Principal. Runs the named Cach routine in application mode with either no device, the console, or the terminal for $Principal. Runs the named Cach routine in the indicated namespace in application mode with either no device, the console, or the terminal for $Principal.

Cach System Administration Guide 7

3
Using Cach on Linux and UNIX
This chapter describes the specific procedures on Linux and UNIX: Starting Cach Stopping Cach

3.1 Starting Cach


To start Cach, run the startup procedure at the system level. This procedure activates either a default configuration or a configuration you specify. If you have any trouble starting Cach, view the console log using the Control Panel as described in the Monitoring Log Files section of the chapter on Managing Cach . If you are not on the console machine, run Telnet and connect to the target machine where Cach is installed. Before you can start Cach on UNIX, one of the following must be true: You are the superuser. You have signed on as the root user. Your UNIX uid group matches the group named during the Cach installation as having privileges to stop and start the system. See the Cach Installation Guide for UNIX and Linux for information on specifying such privileges during installation. Start Cach using the ccontrol command:
Cach System Administration Guide 9

Using Cach on Linux and UNIX


ccontrol start <configname>

where configname is the name of the configuration you want to start. See Controlling Cach Instances for more options and information.

3.2 Stopping Cach


Normally you will leave your Cach system running. However, if your operating system requires a restart, you should stop Cach before you shut down your system. The Cach maintenance tasks, such as backups and database repair utilities, do not require you to stop Cach. To stop Cach on UNIX, the same requirements exist as for starting Cach. One of the following must be true: You are the superuser or you are signed on as the root user. Your UNIX uid group matches the group named during the Cach installation as having privileges to stop and start the system.

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.

10 Cach System Administration Guide

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.

Cach System Administration Guide 11

4
Using Cach on OpenVMS
This chapter describes the following procedures on OpenVMS: Starting Cach Stopping Cach

4.1 Starting Cach


If you are not on the console machine, run Telnet and connect to the target machine where Cach is installed. Before you can start Cach on OpenVMS, one of the following must be true: You are logged into OpenVMS as the system manager. You have access to CMKRNL, WORLD, BYPASS, SYSLCK, ALTPRI, and OPER privileges.

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:

Cach System Administration Guide 13

Using Cach on OpenVMS


ccontrol start <configname>

where configname is the configuration name that you chose during the installation. See Controlling Cach Instances for more options and information.

4.2 Stopping Cach


To stop Cach on OpenVMS, the requirements are the same for starting Cach. You must have access to CMKRNL, WORLD, BYPASS, SYSLCK, ALTPRI, and OPER privileges. You should have these privileges if you are logged on OpenVMS as the system manager. To stop Cach: 1. Use the ccontrol command:
ccontrol stop <configname>

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.

14 Cach System Administration Guide

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

5.1 Cach Instances


There are many ways to connect to an instance of Cach. Two of the most common ways are through the Cach Cube and from the command line of the console. As you install each instance of Cach you give it a configuration name. To perform procedures on a particular instance of Cach, use this name. You can start, stop, and maintain each of these instances independently. You can have multiple Cach Cubes, one for each instance you have installed on your machine. All of the cube utility functions operate within the context of the instance associated with that cube. There is a limit of fifty Cach instances that may be installed on a single machine.

Cach System Administration Guide 15

Using Multiple Instances of Cach

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.

5.2 Connecting to a Cach Instance


Once you have started Cach, run and log on to the Cach shell using the csession command:
csession <configname>

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.

csession <configname> -"U" "namespace" csession <configname> "[label[+offset]]^routine"

To use application mode or the Cach command line on a remote server use a Telnet client, LAT terminal, or the Cach Terminal.

16 Cach System Administration Guide

Controlling Cach Instances

5.3 Controlling Cach Instances


You can control multiple instances of Cach using the ccontrol command. The ccontrol command supports a number of functions and has the following syntax:
ccontrol <function> <configname> [arguments]

Cach ccontrol Command and Functions


Command ccontrol start <configname> [args] {configfile} ccontrol stop <configname> [args] ccontrol force <configname> ccontrol list ccontrol all ccontrol stat <configname> [args] ccontrol help [start | stop | force] ccontrol load <configname>* ccontrol unload <configname>* ccontrol rename <configname> {newname} Description Brings up a configuration. Shuts down a configuration. Forces a configuration down. Lists all installed configurations. Shows compact summary of all configurations. Retrieves system statistics. Gives function-specific help for the start, stop, and force functions. Runs the procedure for loading images. Runs the procedure for unloading images. Renames the configuration file.

* 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)

Cach System Administration Guide 17

Using Multiple Instances of Cach

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.

5.4 Configuring Multiple Cach Instances


You can install and simultaneously run multiple instances of Cach 4.0 and later on a single machine. Install Cach as for a single installation, giving each configuration a unique name, a unique installation directory, and a unique port number for the SuperServer, Telnet, and the License Manager. The special considerations for multiple instances are: Each instance must be version 4.0 or later of Cach. For example, Cach 5.0 and 3.2.1 cannot run on the same machine at the same time. Multiple instances can share the same multiserver key, but if they do, they must use the same license manager or set of license managers. Each system running an instance of Cach under the auspices of one or more license managers must have a local copy of the authorizing license key file installed in every configuration. Multiple instances can be networked. Protection is included against simultaneous database use (that is, each instance must have its own databases and cannot access or modify another instance's databases). Only one configuration per NIC (network interface card) can use DDP (Distributed Data Protocol) or DCP (Distributed Cache Protocol) over Ethernet. DDP and DCP are older distributed data protocols that are supported for interoperation with legacy applications. If a machine has more than one NIC, each configuration must point to a unique NIC. This restriction does not apply to DCP over UDP (User Datagram Protocol).

18 Cach System Administration Guide

Configuring Multiple Cach Instances

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:

5.4.1 Set Port Numbers


For a standard, single configuration of Cach, the SuperServer port number is 1972 by default and is set automatically during installation. Do not change this unless you are running multiple instances on the same machine. For multiple instances of Cach 4.0 and later on a single machine, each must have a unique port number. If an existing instance is running on port number 1972, either change its port number before installing a new configuration, or stop it, install the new instance, and change the port number of the new instance before restarting the existing one. To change the port number on a new installation: 1. From the Cach Cube of a Windows client, point to Preferred Server and click Add/Edit to add a remote server connection to the new Cach configuration. Enter 1972 for the Port of this new installation. 2. Point to Remote System Access from the cube, point to Configuration Manager, and then click the appropriate connection server name you entered for this configuration. If configuring a local instance, choose LOCALTCP as the preferred server or choose Configuration Manager directly from the cube menu. 3. On the Advanced tab of the Configuration Manager, expand the section for General settings. 4. Change the value for Default Port Number from 1972 to a unique number. A restart of Cach is required to activate this change. 5. After restarting, point to Preferred Server and click Add/Edit to edit the remote server connection to the newly installed Cach configuration. Change the port number on the remote server to match the unique port number you assigned this configuration in the previous step. This ensures that the Cach GUI tools connect to the correct Cach instance.

Cach System Administration Guide 19

Using Multiple Instances of Cach

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.

20 Cach System Administration Guide

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.

Cach System Administration Guide 21

Connecting to Remote Servers

6.1 Define a Remote Server Connection


To use the Cach Cube utilities on a remote server, the server must be on the preferred server list. This is a list of remote servers you have previously defined to which you can quickly connect. A remote server is defined with an IP address for a unique server and a TCP port, which is an instance of Cach on that server. To define the remote server: 1. From the Cach Cube menu, point to Preferred Server, and click Add/Edit. 2. Click Add to open the Add Connection dialog box. 3. Fill in the fields as described in the following table and click OK. Each field is required unless otherwise indicated. Add Connection Input Fields
Input Field Server Name TCP/IP Host Description A descriptive phrase that identifies the server; it is what appears as a selection in the Cach Cube. The IP address, host name (if you have a DNS server) or the fully qualified domain name (FQDN) of the remote server. Cach accepts any legitimate name reference for the remote server. The port number of the SuperServer. The default port number is 1972. Optional A description of the remote server.

Port Number Comment

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.

22 Cach System Administration Guide

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.

7.1 Configuring System Information


Cach stores all system-wide configuration information in a configuration file. By default, the file is stored in the Cach root directory with the .cpf file extension. Cach initially starts

Cach System Administration Guide 23

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.

7.2 Configuring Databases


A database is a cache.dat file you create in the Database tab. A Cach database holds data in multidimensional arrays called globals and executable content called routines, as well as class and table definitions. Globals and routines encompass such things as methods, classes, Web pages (CSP and HTML), SQL, BASIC, and JavaScript files.
24 Cach System Administration Guide

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.

Cach System Administration Guide 25

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.

26 Cach System Administration Guide

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.

7.3 Configuring Namespaces


A namespace is a collection of data and programs in a virtual work space. In a namespace, you can define the globals that various groups or people need. For example, if your accounting department needs to use certain globals that exist on different systems or in different directories, you can set up a single namespace that references all the accounting globals and databases on your network. The following procedures for configuring namespaces are described for the Windows platform using the Cach Configuration Manager. When you are finished configuring your namespaces, click OK to save your changes and exit the Configuration Manager. Create a Namespace Change a Namespace Name

Cach System Administration Guide 27

Configuring Cach

Modify Database Mapping Add Global and Routine Mapping to a Namespace Change the Size of the Namespace Table

7.3.1 Create a Namespace


You can create a new namespace at any time, but when you are first setting up the system, create the basic ones that your users need. Cach provides a wizard: 1. From the Configuration Manager, click Wizards, select Create a Namespace and click OK, or click Add from the Namespaces tab. 2. Follow the dialog directions to enter the name and to select a database.

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.

7.3.2 Change a Namespace Name


Cach allows you to change the name of your namespace without requiring a restart.

28 Cach System Administration Guide

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.

7.3.3 Modify Database Mapping


You can change the database to which your namespace is mapped without restarting Cach.

Cach System Administration Guide 29

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.

7.3.4 Add Global and Routine Mapping to a Namespace


In addition to having access to the globals and routines in the mapped database, you can also map globals and routines from other databases on the same or different systems. This allows simple references to data which can exist anywhere and is the primary feature of a namespace. You can map whole globals or pieces of globals; this feature allows data to easily span disks. The process is: 1. From the Namespaces tab, expand the desired namespace.

30 Cach System Administration Guide

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.

Cach System Administration Guide 31

Configuring Cach

7.3.5 Change the Size of the Namespace Table


The maximum number of Cach namespaces depends on the size of the namespace table. Modify this value using the Configuration Manager: 1. From the Advanced tab, expand the Memory settings. 2. Select Namespace Table, and click Change. 3. Enter the size of the namespace table. The range is 16384-32768 bytes. 4. Click OK to update the configuration.

7.4 Configuring License Managers


If you purchased multiserver licenses, you must configure one or more Cach license managers to allocate the Cach license units authorized by the key. All configurations sharing a key must be configured to use the same license manager or set of license managers. License managers can run on any computer where you run a Cach configuration. The license manager is not a Cach process; it is unaffected if a Cach configuration shuts down. Therefore, you need at most one per system regardless of how many Cach configurations run on a system. Each system running an instance of Cach under the auspices of one or more license managers must have a local copy of the authorizing license key file installed in every configuration. If you run Cach servers on multiple hosts, you can configure more than one license manager to provide redundancy. The only requirement is that configurations that share a license must use the same license manager or set of managers. License managers are configured from the Advanced tab of the Configuration Manager. First, expand the License branch by clicking the plus sign, then expand the License Manager folder and any subsequent named license manager folders.

32 Cach System Administration Guide

Configuring License Managers

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.

Cach System Administration Guide 33

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

8.1 Controlling Cach Processes


A Cach system runs a number of processes. Application code as well as Cach system code executes within these processes. There are three categories of Cach processes: User processes, created when a user connects to Cach. Background processes, created when a user issues a Cach ObjectScript Job command. Cach system processes.

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:

Cach System Administration Guide 35

Managing Cach

Control Panel Functions


Process management function Display process information Display process details How to access function from the Control Panel Click the Processes task folder. Click Details on the shortcut menu* of the selected process. Click Suspend, Resume, or Terminate as desired on the shortcut menu* of the selected process. Click Debug on the shortcut menu* of the selected process. Click Broadcast Message on the shortcut menu* of the selected process. Click the Local Databases task folder. Click the Lock Table task folder. Click the Logs task folder.

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.

8.1.1 Display Process Information


To display all the active processes on the system and basic information about each, click the Processes task folder in the Control Panel. The contents window displays a table of the processes with statistics about each in columns.

36 Cach System Administration Guide

Controlling Cach Processes

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.

Lines Executed/ Sec

Cach System Administration Guide 37

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.

User Name Client Name Exe Name IP Address

* 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.

38 Cach System Administration Guide

Controlling Cach Processes

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

8.1.2 Display Process Details


You can display more detailed information about any process using the Cach Control Panel: 1. Click the Processes task folder. 2. Right-click the process in the contents window. 3. Click Details on the shortcut menu; Cach opens the Process Details dialog box for the selected process.

Cach System Administration Guide 39

Managing Cach

8.1.3 Stopping a Process


You can stop a process in one of two ways: Suspend a process with the intention of resuming the process later. Terminate a process, which entirely cancels the process.

8.1.3.1 Suspend a Process


You may want to suspend a process if you are not sure what a process is doing and want to investigate, or if a more important process is trying to run and needs the CPU cycles. From the Control Panel: 1. Click the Processes task folder. 2. Right-click the process in the contents window. 3. Click Suspend on the shortcut menu. You may resume a suspended process at any time by clicking Resume from the same shortcut menu.
40 Cach System Administration Guide

Controlling Cach Processes

8.1.3.2 Terminate a Process


You may want to terminate a process if it becomes unresponsive or is affecting other processes or users. From the Control Panel: 1. Click the Processes task folder. 2. Right-click the process in the contents window. 3. Click Terminate on the shortcut menu. 4. Click Yes to confirm that you want to terminate the process. There is no way to resume a terminated process.

8.1.4 Debug a Process


Cach allows you to access the Debug utility using the Control Panel. This provides you with the tools needed to debug a process or a routine you have started as a process. 1. Click the Processes task folder. 2. Right-click the process in the contents window. 3. Click Debug on the shortcut menu. 4. Cach places you in the Debug utility to debug the selected process. All the standard Debug commands and functions are applicable as described in the Command-Line Routine Debugging chapter of Use Cach ObjectScript. Please also reference Debugging in the Introduction chapter of Using Cach Studio, which describes using the graphical source-level debugger included with Cach Studio.

8.1.5 Broadcast Messages to Terminals


You can broadcast messages to the terminals associated with a selected process, or all processes. These utilities are useful for asking people to sign off the system. However, you must use them carefully or you may cause messages to appear in the middle of reports that may be printing at the time. The utility temporarily takes control of each terminal as it sends the message. Once the terminal receives the message, the previous job continues. The message will appear on the terminal screen; it may disrupt the screen display, but it does not affect user input. The message does not appear in windows running Cach utilities.

Cach System Administration Guide 41

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.

8.2 Monitoring Local Databases


You can accomplish many database and global management tasks through the Local Databases folder in the Cach Control Panel. To view basic information about each database: 1. Click Control Panel on the Cach Cube. 2. Click Local Databases. Cach displays the list of databases to the right of the folder list. For each database, you see the following information.

42 Cach System Administration Guide

Monitoring Locks

Local Databases Information


Column Heading
Database Directory Status

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.

Cur Size Cur % Full

Max Size Max % Full Clustered

Block Size 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\

8.3 Monitoring Locks


Cach locks are created when a Cach process issues a Lock command on a Cach entity, such as a local or global variable, as long as the entity is not already locked by another process. Items need not exist in the database in order to lock them. To display or delete locks, click the Lock Table task folder in the Cach Control Panel.

Cach System Administration Guide 43

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.

Shared Waiters # Flags

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

Monitoring Log Files

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.

8.4 Monitoring Log Files


Cach reports general messages, system errors, certain operating system errors, and network errors through an operator console facility. For Cach Windows-based systems, there is no operator console as such and all console messages are sent to a log file, cconsole.log, in the system manager namespace, typically CacheSys\Mgr. For Cach systems on UNIX or OpenVMS platforms, you can send operator console messages to the console log file or the console terminal. The console log file is a plain text file and may be viewed with any editor or text viewer including the log viewer included in the Cach Control Panel: 1. Expand the Logs task folder. 2. Click Console Log and a dialog box displays the contents of the console log file:

Cach System Administration Guide 45

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.

46 Cach System Administration Guide

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.

Cach System Administration Guide 47

Achieving High Availability

9.1 Surviving a Crash


Both internal and physical integrity can be threatened by hardware failures caused by malfunctions or external events such as fire or loss of electric power. However, modern hardware helps avoid system crashes, and Cach contains safeguards and offers strategies that allow you to recover data as quickly and completely as possible. Two mechanisms critical to the recovery process are write image journaling and establishing a consistent journaling and backup strategy.

9.1.1 Write Image Journaling


Write image journaling maintains the internal integrity of the Cach database, and is the foundation of the database recovery process. Write image journaling is automatically enabled when you start Cach, and works for all Cach directories. Rather than writing directly from memory to the database, the Cach Write daemon system process (WRTDMN) uses an intermediate file, the write image journal. This file is usually named cache.wij. On UNIX systems, you may specify a UNIX raw partition in your system configuration. Write image journaling technology uses a two-phase process of writing to the database, as follows: In the first phase, Cach records the changes needed to complete the update in the write image journal. Once all updates to the write image journal have been entered, a flag is set in the file and the second phase begins. In the second phase, the Write daemon writes the changes recorded in the write image journal to the database on disk. When this second phase completes, the Write daemon sets a flag in the write image journal to indicate it is empty.

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.

48 Cach System Administration Guide

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:

9.2 Backup Strategy


The best and most common strategy for backing up Cach databases is to perform daily online concurrent backups during the slowest period of a production day. You do not have to stop Cach to back up your data. Cach maintains a bitmap list of database blocks modified since the last backup; you can use this list to keep track of database updates during backup stages. The DBSIZE utility, which inspects these bitmaps, helps you calculate the size of a backup. Cach BACKUP uses a multipass scan of these lists to back up only the blocks modified since the last pass. Subsequent passes usually operate on a reduced list of modified blocks; generally three passes are sufficient to complete a backup. During the final pass, Cach suspends all processes to prevent updates and allow the backup to completely copy the last short list of modified blocks. This method is used in most of the backup strategies that follow: Concurrent External Backup Non-concurrent External Backup Concurrent Cach Backup Cold Backup

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.

Cach System Administration Guide 49

Achieving High Availability

9.2.1 Concurrent External Backup


A concurrent external backup, or dirty backup, is the most common strategy used by largescale production facilities that have large databases, have limited time to complete a backup, and require uninterrupted processing 24 hours a day. The utility you use to perform the backup depends on your preference and the operating system. You may choose a native operating system utility, such as the tar utility on UNIX, or a third-party utility such as Veritas or ARCserve. Cach makes it easy to integrate with such utilities. The following is an example of a UNIX procedure: 1. Clear the list of database blocks modified since the last backup. This synchronization point later allows you to identify all database blocks modified during the backup. Call the application program interface (API), CLRINC^DBACK("QUIET"), in the backup script; this completes instantly. 2. Using your preferred backup utility, copy the CACHE.DAT files which may be in use. 3. Perform an incremental backup of the blocks modified by users during the backup. This should be an output sequential file. Since it is likely to be a small set of blocks, this step should complete very quickly. Call the API, BACKUP^DBACK(), in the backup script. Important: The journal file should be switched at this time.

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

CLRINC and BACKUP("","E") are performed in one Cach session.

9.2.2 Non-Concurrent External Backup


A non-concurrent external backup, or paused backup, is the second most common strategy used by large-scale production facilities that have large databases and limited time to complete a backup, but can tolerate a brief operational pause. This strategy is often used in conjunction with advanced disk technologies, such as disk mirroring. The approach is to safely pause Cach long enough to separate a mirror copy of data and then quickly allow Cach to continue

50 Cach System Administration Guide

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.

9.2.3 Concurrent Cach Backup


The concurrent Cach backup strategy is used when the backup must complete without interrupting Cach processing; for example, if daily incremental backups are performed rather than complete backups. You can do this using interactive utilities, such as Do ^BACKUP, or through the API BACKUP^DBACK. Note: The utilities BACKUP and DBACK allow you to select a full backup of all blocks in use, an incremental backup of only the blocks modified since the last incremental backup, or a cumulative, incremental backup of the blocks modified since the last full backup.

9.2.4 Cold Backup


The cold backup strategy is generally used in the rare case when the operation tolerates downtime. Sometimes, this is done only when performing a complete system backup as part of a maintenance effort such as repairing faulty hardware. In this situation, stop Cach during the backup period and restart it when the backup completes: 1. Stop Cach using the ccontrol command or through the Cach Cube. 2. Perform the backup.
Cach System Administration Guide 51

Achieving High Availability

3. Restart Cach using the ccontrol command or through the Cach Cube.

9.3 Logical Data Protection


Applications need to ensure that sets of related database changes work correctly. This type of application integrity is called logical integrity. Cach protects the logical integrity of databases using the following: Transaction Processing Transactions and Locking Global Journaling

For more information, see the Transaction Processing chapter of Using Cach ObjectScript and the Managing Transactions section in Using Multidimensional Storage.

9.3.1 Transaction Processing


A set of related changes is called a transaction. Examples include updating a patient's medical record, transferring funds from one bank account to another, and reserving an airline seat. In general, you must define the scope of a transaction although Cach can infer the boundaries in some cases. For example, suppose that the computer malfunctions during a transaction. The two-phase write protocol protects the internal integrity of the database, but not the logical or application-level integrity. It does not prevent you from ending up with half of a patient record or two-thirds of airline seat processing. The best protection is offered by transaction processing. In a Cach application, the start of a unit of work is indicated with a TStart command. If the transaction completes normally, a TCommit command is issued. If a transaction does not complete successfully, Cach performs a process called rollback, in which all values altered by the transaction are restored to their prior state. When a transaction is rolled back, it is as if the failed transaction never occurred. Three situations may trigger a rollback: The application itself may detect a problem and request a rollback. Often this is done from an application error-handling routine following an error. You can use Cach ObjectScript to implement these techniques in your application, or rely on automatic transaction processing in Cach SQL.

52 Cach System Administration Guide

Logical Data Protection

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.

9.3.2 Transactions and Locking


You use the Lock command in Cach applications to protect against simultaneous access to data. For example, an application might contain the following steps:
TSTART //begin transaction Lock +^SAVINGS(ACCOUNT,"BALANCE") //lock record Set ^SAVINGS(ACCOUNT,"BALANCE") = ^SAVINGS(ACCOUNT,"BALANCE") - 100 Lock -^SAVINGS(ACCOUNT,"BALANCE") //unlock record Lock +^CHECKING(ACCOUNT,"BALANCE") //lock record Set ^CHECKING(ACCOUNT,"BALANCE") = ^CHECKING(ACCOUNT,"BALANCE") + 100 Lock -^CHECKING(ACCOUNT,"BALANCE") //unlock record TCOMMIT

Cach System Administration Guide 53

Achieving High Availability

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.

9.3.3 Global Journaling


Global journaling preserves changes in the database since the last backup. While a backup is the cornerstone of physical recovery, it is not the complete answer. Restoring the database from a backup makes the contents of the database current as of the time the backup was completed. Typically, this will be a long time (at least a number of hours) before the point at which physical integrity was lost. What happens to all the database changes that occurred since then? The answer lies with journaling. Each computer running Cach keeps a journal. The journal is a file that keeps a time-sequenced log of changes that have been made to the database since the last backup. The process is redundant and logical and does not use the Cach Write daemon. You can turn on journaling for all modifications to the database, or enable selectively on a global-by-global basis. The default setting is to journal all globals, except those stored in CACHETEMP. Selective journaling avoids the overhead of saving updates to databases or globals for which recovery is not needed. Cach transaction processing works with journaling to maintain the logical integrity of data. The journal also contains Set and Kill operations for all globals marked for journaling.

54 Cach System Administration Guide

Database Integrity Protection

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.

9.4 Database Integrity Protection


To recover databases after a loss of structural integrity, restore the backup and then apply the subsequent database changes from the journal. This Cach recovery process is designed to provide maximal protection: It uses the roll forward approach. If a system crash occurs, the recovery mechanism completes the updates that were in progress. By contrast, other systems employ a roll back approach, undoing updates to recover. While both approaches protect internal integrity, the roll forward approach used by Cach does so with reduced data loss. Cach protects the sequence of updates: if an update is present in the database following recovery, preceding updates are also present. Other systems which do not correctly pre-

Cach System Administration Guide 55

Achieving High Availability

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.

9.4.1 Database Integrity Checking


The procedure for checking database integrity from the Control Panel is as follows: Right-click the Local Databases task folder, three items related to database integrity checking are available at this level and one at the individual database level:

9.4.1.1 Check Integrity for All Databases


You can check the integrity of all local databases: 1. Click Integrity Check after right-clicking Local Databases. 2. The Job Status dialog box opens and the check begins. 3. From the Options menu, you can select Iconize on Startup. This makes the Job Status dialog box run minimized and opens it when the job is complete so that you can check the log. 4. From the File menu, you may save the log to a file, print it, or exit the Job Status dialog box.

9.4.1.2 Check Integrity for All Databases in the Background


You can check the integrity of all the local databases by initiating a background job: 1. Click Background Integrity Check after right-clicking Local Databases. 2. Enter the name and location of a log file in the dialog box that appears. After entering the appropriate information, click OK to start the job.

9.4.1.3 View the Output from the Background Integrity Check


You can view the log resulting from the background job: 1. Click View Integrity Log after right-clicking Local Databases.

56 Cach System Administration Guide

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.

9.4.1.4 Check the Integrity of an Individual Database


You can also check the integrity of a specific database, one database at a time. 1. Expand the Local Databases task folder and right-click the appropriate database. 2. Click Integrity Check and view the job status the same way as on all the databases.

9.4.2 Database Integrity Checking Utility


You can also use the utility routine ^Integrity. The name is case-sensitive and you call it from the Cach manager's namespace with Do ^Integrity. This is the equivalent of running Integrity Check on Local Databases from the Control Panel. There are three additional entry points to this routine:
Do CheckPointer^Integrity asks for a directory and a pointer block at which to start

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.

9.5 Shadow Journaling


Shadow journaling enables a secondary computer to maintain a shadow version of selected databases as they are updated on a primary machine. By continually transferring journal
Cach System Administration Guide 57

Achieving High Availability

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.

9.6 System Failover Strategies


Cach fits into all common high availability configurations promoted by operating system providers, including Microsoft, IBM, HP, Compaq, and EMC. Cach provides easy-to-use, often automatic, mechanisms that integrate easily with the operating system to provide high availability. There are four general approaches, in the order of increasing availability: No Failoverfor applications that are most likely not business-critical. Cold Failovera common and inexpensive approach that involves switching to a standby system in case of a failure. Warm Failoverexploits a standby system that is ready to accept users instantly after a production system failure. Hot Failovercan be complicated and expensive, but comes closest to ensuring 100% uptime.

58 Cach System Administration Guide

System Failover Strategies

Failover Strategy Impact


Approach No Failover Cold Failover Warm Failover Hot Failover Recovery Time Unpredictable Minutes Seconds Immediate Expense No cost to low cost Moderate Moderate to high Moderate to high User Impact High Moderate Low None

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.

Cach System Administration Guide 59

Vous aimerez peut-être aussi