Gsa

Caché SystemAdministration Guide

Version 5.0.1730 June 2005

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

Caché System Administration GuideCaché 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 fromthe following sources: Sun Microsystems, RenderX, Inc., Adobe Systems, and the World Wide Web Consortium atwww.w3c.org. The primary document development tools were special-purpose XML-processing applications builtby 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 operationand maintenance of the products of InterSystems Corporation. No part of this publication is to be used for any otherpurpose, and this publication is not to be reproduced, copied, disclosed, transmitted, stored in a retrieval system ortranslated into any human or computer language, in any form, by any means, in whole or in part, without the expressprior written consent of InterSystems Corporation.

The copying, use and disposition of this document and the software programs described herein is prohibited exceptto the limited extent set forth in the standard software license agreement(s) of InterSystems Corporation coveringsuch programs and related documentation. InterSystems Corporation makes no representations and warrantiesconcerning such software programs other than those set forth in such standard software license agreement(s). Inaddition, the liability of InterSystems Corporation for any losses or damages relating to or arising out of the use ofsuch 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 BYINTERSYSTEMS CORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTERSOFTWARE. FOR COMPLETE INFORMATION REFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARELICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION, COPIES OF WHICH WILL BE MADE AVAILABLEUPON REQUEST.

InterSystems Corporation disclaims responsibility for errors which may appear in this document, and it reserves theright, in its sole discretion and without notice, to make substitutions and modifications in the products and practicesdescribed 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 productnames 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+1 617 621-0700Tel:+1 617 374-9391Fax:[email protected]:

Table of Contents

1 Introduction ..................................................................................................................... 1

2 Using Caché on Windows ................................................................................................ 32.1 Caché Cube .............................................................................................................. 32.2 Starting Caché .......................................................................................................... 52.3 Stopping Caché ........................................................................................................ 62.4 Controlling Caché from the Command Prompt ....................................................... 7

3 Using Caché on Linux and UNIX ................................................................................... 93.1 Starting Caché .......................................................................................................... 93.2 Stopping Caché ...................................................................................................... 10

4 Using Caché on OpenVMS ........................................................................................... 134.1 Starting Caché ........................................................................................................ 134.2 Stopping Caché ...................................................................................................... 14

5 Using Multiple Instances of Caché ............................................................................... 155.1 Caché Instances ...................................................................................................... 155.2 Connecting to a Caché Instance ............................................................................. 165.3 Controlling Caché Instances .................................................................................. 175.4 Configuring Multiple Caché Instances .................................................................. 18

5.4.1 Set Port Numbers .......................................................................................... 19

6 Connecting to Remote Servers ..................................................................................... 216.1 Define a Remote Server Connection ...................................................................... 22

7 Configuring Caché ......................................................................................................... 237.1 Configuring System Information ........................................................................... 237.2 Configuring Databases ........................................................................................... 247.3 Configuring Namespaces ....................................................................................... 27

7.3.1 Create a Namespace ..................................................................................... 287.3.2 Change a Namespace Name ......................................................................... 287.3.3 Modify Database Mapping ........................................................................... 297.3.4 Add Global and Routine Mapping to a Namespace ..................................... 307.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 .................................................................................. 358.1.1 Display Process Information ........................................................................ 368.1.2 Display Process Details ................................................................................ 398.1.3 Stopping a Process ........................................................................................ 408.1.4 Debug a Process ........................................................................................... 418.1.5 Broadcast Messages to Terminals ................................................................ 41

8.2 Monitoring Local Databases .................................................................................. 428.3 Monitoring Locks ................................................................................................... 438.4 Monitoring Log Files ............................................................................................. 45

9 Achieving High Availability .......................................................................................... 479.1 Surviving a Crash ................................................................................................... 48

9.1.1 Write Image Journaling ................................................................................ 489.2 Backup Strategy ..................................................................................................... 49

9.2.1 Concurrent External Backup ........................................................................ 509.2.2 Non-Concurrent External Backup ................................................................ 509.2.3 Concurrent Caché Backup ............................................................................ 519.2.4 Cold Backup ................................................................................................. 51

9.3 Logical Data Protection ......................................................................................... 529.3.1 Transaction Processing ................................................................................. 529.3.2 Transactions and Locking ............................................................................. 539.3.3 Global Journaling ......................................................................................... 54

9.4 Database Integrity Protection ................................................................................. 559.4.1 Database Integrity Checking ........................................................................ 569.4.2 Database Integrity Checking Utility ............................................................. 57

9.5 Shadow Journaling ................................................................................................. 579.6 System Failover Strategies ..................................................................................... 58

iv Caché System Administration Guide

List of Figures

Caché Cube Menu ................................................................................................................ 4Sample Namespace Mapping ............................................................................................. 31

Caché System Administration Guide v

List of Tables

Caché Cube Commands ....................................................................................................... 4Control Commands ............................................................................................................. 16Caché csession Command and Arguments ......................................................................... 16Caché ccontrol Command and Functions ........................................................................... 17Add Connection Input Fields .............................................................................................. 22Control Panel Functions ..................................................................................................... 36Process Column Information .............................................................................................. 37Possible Process States ....................................................................................................... 38Local Databases Information .............................................................................................. 43Lock Table Information ...................................................................................................... 44Failover Strategy Impact ..................................................................................................... 59

vi Caché System Administration Guide

1Introduction

This book is an introduction to accessing and running a Caché system. Managing Caché iseasy; whether running on a single PC or on a system of thousands of users, most of theinformation you need to get the system running is contained in this document.

Caché is available on a number of different operating systems. Certain administrative proce-dures and tasks may differ according to platform. Where this is the case, this documentdescribes these differences.

Caché offers many different ways to perform system administration. On Microsoft Windowssystems, 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é submenuof the Windows Programs menu). These graphical utilities are client/server applications thatcan 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

• Achieving High Availability

2 Caché System Administration Guide

Introduction

2Using Caché on Windows

The primary Caché interface is the Caché Cube. From the Caché Cube, you can start all ofthe Caché configuration and management tools. You can also invoke each Cube commandfrom a shortcut or command line.

Correspondingly, you can initiate many of the Caché tools from the Windows Start menu bypointing 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 appears in the systemtray of the taskbar.

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


Caché Cube Menu

You can only use the Caché Cube menu from Windows. The Caché Cube provides a simpleinterface 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

FunctionCaché Cube Command

Displays tutorials, release notes, and documentation.Getting Started

Starts the default configuration specified in the squarebrackets after the menu item, for example [CACHE]. If theCaché server is already started, this option appearsdimmed—it is unavailable.

Start Caché

Shuts down or restarts the local Caché configuration.Stop Caché

Creates, edits, deletes, and compiles Caché classdefinitions, CSP (Caché Server Pages) pages, Caché Basicroutines, and Caché ObjectScript routines. See Using CachéStudio.

Studio

Invokes the command line interpreter in the Cachéprogramming environment.

Terminal


Using Caché on Windows

FunctionCaché Cube Command

Displays classes, globals, and routines, and functions formanaging each.

Explorer

Displays tables and views, perform queries and SQLmanagement functions. See Using Caché SQL Manager.

SQL Manager

Performs common system management tasks. SeeManaging Caché.

Control Panel

Creates databases and namespaces, and adjusts all Cachéconfiguration settings. See Configuring Caché.

Configuration Manager

Displays Caché online documentation.Documentation

Displays a submenu of all the Caché utilities with access toany defined remote Caché server. The Caché Telnet

command starts the Caché terminal emulator and allowsyou to choose your host from within the Telnet window.

Remote System Access

Shows a list of remote servers and maintains serverconnections by using the Add/Edit command on the submenu.The preferred server has a check mark next to it.

Preferred Server [Servername]

Displays Caché version and build information.About

Removes the Caché Cube icon from the system tray; thisdoes not stop Caché.

Exit

2.2 Starting Caché

To start Caché, run the startup procedure at the system level. This procedure activates eithera default configuration or a configuration you specify.

If you have any trouble starting Caché, view the console log using the Control Panel asdescribed 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 startsthe Caché system specified as the default configuration. When Caché is not running, theCaché 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,


Starting Caché

access the Bin folder in the Caché configuration directory (CacheSys by default) and double-click the csystray.exe file.

Alternatively, you can enter these commands from the <cache-install-dir>/bin directory in theOpen box of the Run item on the Windows Start menu. For example, to start the configurationnamed 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 requiresa restart, stop Caché before you shut down your system. The Caché maintenance tasks, suchas 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é config-uration. By default, this option shuts down (or restarts) Caché immediately, using the defaultshutdown 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 userson the server. InterSystems recommends that you use Stop Caché to shut down Caché toensure that it closes properly.

Note: You cannot cancel a shutdown once the countdown reaches 0 and the shutdownprocedures have started.


Using Caché on Windows

2.4 Controlling Caché from the CommandPrompt

You can also control a Caché configuration from the Windows command prompt by runningthe css.exe program in the <cache-install-dir>\Bin directory.

DescriptionCommand

Starts the specified configuration.css start <configname>

Shuts down the named configuration.css stop <configname>

Shuts down the named configuration usingINTNOSHUT^SHUTDOWN.

css stopnoshut <configname>

Shuts down and restarts the named configuration.css stopstart <configname>

Forces down the named configuration.css force <configname>

Runs Caché in programmer mode with either nodevice, the console, or the terminal for $Principal.

css [run | console | cterminal]<configname>

Runs the named Caché routine in application modewith either no device, the console, or the terminal for$Principal.

css [run | console | cterminal]<configname> <routine>

Runs the named Caché routine in the indicatednamespace in application mode with either no device,the console, or the terminal for $Principal.

css [run | console | cterminal]<configname> <routine><namespace>


Controlling Caché from the Command Prompt

3Using 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 eithera default configuration or a configuration you specify.

If you have any trouble starting Caché, view the console log using the Control Panel asdescribed 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 whereCaché 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 havingprivileges to stop and start the system.

See the Caché Installation Guide for UNIX and Linux for information on specifying suchprivileges during installation.

Start Caché using the ccontrol command:


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 systemrequires 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 stopCaché.

To stop Caché on UNIX, the same requirements exist as for starting Caché. One of the fol-lowing 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 havingprivileges 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 ControllingCaché 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=> YesSend a message to other terminals. Message => Please sign offTerminal => /dev/tty/06Terminal =>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 seeone, or press Enter if you do not want another report.


Using Caché on Linux and UNIX

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 procedurequits and Caché continues running.


Stopping Caché

4Using 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 whereCaché is installed. Before you can start Caché on OpenVMS, one of the following must betrue:

• You are logged into OpenVMS as the system manager.

• You have access to CMKRNL, WORLD, BYPASS, SYSLCK, ALTPRI, and OPERprivileges.

Run the Caché startup procedure. The distribution includes a template of this startup commandprocedure, CACHE$STARTUP.COM; modify this file as necessary for your site.

Run CACHE$STARTUP.COM at the operating system level when you restart OpenVMS, aswell as when you install or upgrade Caché.

To start Caché, modify the CACHE$STARTUP.COM file to automatically start the desiredCaché 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:


ccontrol start <configname>

where configname is the configuration name that you chose during the installation. SeeControlling 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 musthave 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. Tostop Caché:

1. Use the ccontrol command:

ccontrol stop <configname>

where configname is the name of the configuration that you want to stop. See ControllingCaché 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 youare about to shut down the Caché system. Enter the message you want to send, and theterminal to which you want to send it. To send a message to several terminals, specifyeach terminal individually. For instance:

Do you want to broadcast a message to anyone? No=>YesSend a message to other terminals. Message => Please sign offTerminal => _NTY5:Terminal => <RETURN>Message =>

4. When the system asks if you would like to see another system status, enter Yes to seeone, 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 procedurequits, and Caché continues running.


Using Caché on OpenVMS

5Using Multiple Instances of Caché

You are not limited to running only one Caché system on a machine. You can install multipleCaché 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 addressesthe 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 arethrough 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 procedureson a particular instance of Caché, use this name. You can start, stop, and maintain each ofthese instances independently. You can have multiple Caché Cubes, one for each instanceyou have installed on your machine. All of the cube utility functions operate within the contextof the instance associated with that cube.

There is a limit of fifty Caché instances that may be installed on a single machine.


To control a Caché instance from the command line, use the configuration name. The followingtable shows the most common commands to manipulate Caché instances.

Control Commands

Caché commandAction desired

ccontrol start <configname>Starting a Caché instance

csession <configname>Connecting to a Caché instance

ccontrol stop <configname>Stopping a Caché instance

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 notlimited to, running remote backups, editing remote configurations, and creating and compilingremote objects and routines. See the chapter on “Connecting to Remote Servers” for moredetailed 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

DescriptionCommand

Provides system administrator login toperform system tasks such as setting uplicensing.

csession <configname> -"B"

Specifies the login namespace.csession <configname> -"U" "namespace"

Runs a routine in user mode.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.


Using Multiple Instances of Caché

5.3 Controlling Caché Instances

You can control multiple instances of Caché using the ccontrol command. The ccontrolcommand supports a number of functions and has the following syntax:

ccontrol <function> <configname> [arguments]

Caché ccontrol Command and Functions

DescriptionCommand

Brings up a configuration.ccontrol start <configname> [args] {configfile}

Shuts down a configuration.ccontrol stop <configname> [args]

Forces a configuration down.ccontrol force <configname>

Lists all installed configurations.ccontrol list

Shows compact summary of allconfigurations.

ccontrol all

Retrieves system statistics.ccontrol stat <configname> [args]

Gives function-specific help for the start,stop, and force functions.

ccontrol help [start | stop | force]

Runs the procedure for loading images.ccontrol load <configname>*

Runs the procedure for unloading images.ccontrol unload <configname>*

Renames the configuration file.ccontrol rename <configname> {newname}

* Functions for OpenVMS only.

In the table above, configname is the name of the configuration that you are managing andconfigfile is an optional alternate configuration file (with a .cpf extension) that is located inthe 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 configu-ration (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)


Controlling Caché Instances

• help — print the help message and exit

• restart — start Caché after a successful shutdown (for stop function only and not availableon 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, amongothers. Caché can accommodate these procedures. These scripts, in fact, are invoked byccontrol. Invoke the ccontrol help command to obtain the most recent description of theinterface with these scripts.

For an example of creating user start and stop procedures, see the Use of the ^%ZSTARTand ^%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 singlemachine. 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, andthe 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.1cannot run on the same machine at the same time.

• Multiple instances can share the same multiserver key, but if they do, they must use thesame license manager or set of license managers. Each system running an instance ofCaché under the auspices of one or more license managers must have a local copy of theauthorizing license key file installed in every configuration.

• Multiple instances can be networked.

• Protection is included against simultaneous database use (that is, each instance must haveits own databases and cannot access or modify another instance's databases).

• Only one configuration per NIC (network interface card) can use DDP (Distributed DataProtocol) or DCP (Distributed Cache Protocol) over Ethernet. DDP and DCP are olderdistributed 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).



• Each instance must have unique port numbers. See the next section for information onhow to Set Port Numbers.

Note: Please see the Multiple Caché Installation Issues section of the Caché InstallationGuide for important facts when installing multiple instances of Caché.

5.4.1 Set Port Numbers

For a standard, single configuration of Caché, the SuperServer port number is 1972 by defaultand is set automatically during installation. Do not change this unless you are running multipleinstances on the same machine.

For multiple instances of Caché 4.0 and later on a single machine, each must have a uniqueport number.

If an existing instance is running on port number 1972, either change its port number beforeinstalling a new configuration, or stop it, install the new instance, and change the port numberof 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 thePort of this new installation.

2. Point to Remote System Access from the cube, point to Configuration Manager, and thenclick the appropriate connection server name you entered for this configuration.

If configuring a local instance, choose LOCALTCP as the preferred server or chooseConfiguration Manager directly from the cube menu.

3. On the Advanced tab of the Configuration Manager, expand the section for General set-tings.

4. Change the value for Default Port Number from 1972 to a unique number. A restart ofCaché is required to activate this change.

5. After restarting, point to Preferred Server and click Add/Edit to edit the remote serverconnection to the newly installed Caché configuration. Change the port number on theremote server to match the unique port number you assigned this configuration in theprevious step. This ensures that the Caché GUI tools connect to the correct Caché instance.


Configuring Multiple Caché Instances

Note: If you frequently use and manage multiple instances of Caché on one machine, itmay be helpful to assign unique port numbers immediately after installing. Theassignment of unique port numbers ensures that the Caché default port number isalways available for use by another installation and avoids confusion when usingthe Caché Cube tools on multiple instances from one Windows client.



6Connecting 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 withyour 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 runningon a PC or from any workstation client capable of running Telnet. This client could possiblyhave only utilities (for the system management of servers) and not a Caché instance. Theversion of Caché on the client PC in most cases, must be the same or a later version of theCaché system it manages.

Note: Users of the Mac OS X platform can also use SSH from a command prompt onWindows to connect to their OS X machine.


6.1 Define a Remote Server Connection

To use the Caché Cube utilities on a remote server, the server must be on the preferred serverlist. This is a list of remote servers you have previously defined to which you can quicklyconnect. 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 requiredunless otherwise indicated.

Add Connection Input Fields

DescriptionInput Field

A descriptive phrase that identifies the server; it is what appears asa selection in the Caché Cube.

Server Name

The IP address, host name (if you have a DNS server) or the fullyqualified domain name (FQDN) of the remote server. Caché acceptsany legitimate name reference for the remote server.

TCP/IP Host

The port number of the SuperServer. The default port number is1972.

Port Number

Optional – A description of the remote server.Comment

Important: The Caché SuperServer must be running on the remote machine and its portmust be open on your firewall to use the Cube utilities on that system.

For security reasons, username and password are no longer stored with theremote connection information.


Connecting to Remote Servers

7Configuring 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 configurationparameters. You can use the Configuration Manager to adjust system settings as well as tocreate 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 torunning most Caché systems. These advanced options are described in various Caché topic-specific 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


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 todisplay boxes for allocating the global buffer pool. You can specify how global buffer poolmemory 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 inmultidimensional arrays called globals and executable content called routines, as well asclass and table definitions. Globals and routines encompass such things as methods, classes,Web pages (CSP and HTML), SQL, BASIC, and JavaScript files.


Configuring Caché

Caché databases dynamically expand as needed, though you can set a maximum limit. Sec-ondary volumes of a database are called cache.ext files. The databases are automaticallymounted 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 canonly have open at one time as many as permitted by the operating system limit on maximumopen files (either per process or system-wide), minus what Caché reserves for its own useand device, which is approximately half.

You can make most database configuration changes dynamically; you can create, delete, ormodify database attributes while the system is running. You can create new databases withan 8-KB block size; you can also create 2-KB databases for backward compatibility withversions 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 byclicking 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 followthe instructions to designate the remote server name or address.


Configuring Databases

3. Select the directory where the database will reside and click Next. If the directory doesnot 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 theolder 2 KB. In the Initial Size box, type or select the number of megabytes for your databasesize.


Configuring Caché

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 toan operating system file called cache.dat or cache.ext, even if it is not a mounteddatabase.

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 accountingdepartment needs to use certain globals that exist on different systems or in different directo-ries, you can set up a single namespace that references all the accounting globals and databaseson your network.

The following procedures for configuring namespaces are described for the Windows platformusing 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


Configuring Namespaces

• 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 clickOK, 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 adefault CSP application for this namespace.

3. When you have completed all the questions, click Finish to add your namespace to theconfiguration.

7.3.2 Change a Namespace Name

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


Configuring Caché

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



1. From the Namespaces tab, expand the desired namespace tree by clicking on the plussign 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 offand 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 alsomap globals and routines from other databases on the same or different systems. This allowssimple 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.


Configuring Caché

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 Globalor Routine table and provides access points for you to change the global or routine map-ping.

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

Sample Namespace Mapping

Data and programs are stored in Caché databases, the physical storage locations, and referredto by namespaces, the logical references.



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 managersto allocate the Caché license units authorized by the key. All configurations sharing a keymust be configured to use the same license manager or set of license managers. Licensemanagers can run on any computer where you run a Caché configuration. The license manageris not a Caché process; it is unaffected if a Caché configuration shuts down. Therefore, youneed 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 managersmust 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 managerto provide redundancy. The only requirement is that configurations that share a license mustuse 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 folderand any subsequent named license manager folders.


Configuring Caché

From this tab, you may add a new license manager, remove a specific license manager, orchange 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 portit 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 managerport number must be a number between 1024 and 65535. InterSystems uses a default portnumber of 4001. Unlike the license servers used in earlier versions of Caché, the port numbersof 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.


Configuring License Managers

8Managing 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 codeexecutes 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:


Control Panel Functions

How to access function from the Control PanelProcess management function

Click the Processes task folder.Display process information

Click Details on the shortcut menu* of the selectedprocess.

Display process details

Click Suspend, Resume, or Terminate as desired onthe shortcut menu* of the selected process.

Stopping a process

Click Debug on the shortcut menu* of the selectedprocess.

Debug a process

Click Broadcast Message on the shortcut menu* ofthe selected process.

Broadcast messages to terminals

Click the Local Databases task folder.Monitoring local databases

Click the Lock Table task folder.Monitoring locks

Click the Logs task folder.Monitoring log files

* You can access the shortcut menu by right-clicking the selected process in the contentswindow.

8.1.1 Display Process Information

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


Managing Caché

You can customize the process display to show only the information that interests you. Fromthe 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 toinclude in the contents window.

3. Click OK.

The following table describes the process information available for display:

Process Column Information

DefinitionColumn Heading

Operating system process identification number.*Process

Current device the process is using.Device

Namespace in which the process is running.Namespace

Name of the routine that the process is currently executing.Routine

Number of lines of source code executed.Lines Executed

Number of global references, including updates, executed(database reads and writes) since the process entered Caché.

Global References

Number of code lines changed since the last update.Lines Executed/ Sec


Controlling Caché Processes


Number of global references changed since the last update.Global Refs/Sec

Process state. See the Possible Process States table below foran explanation of each state.

State

Name of the user who owns the process.User Name

Name of the client system that initiated the process.Client Name

Name of the executable that called the process.Exe Name

IP Address of the system that initiated the process.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 callininterface from $ZF routines.

The following table lists the possible process states as displayed in the process informationtable:

Possible Process States

ProcessState

Performing a Caché lock.LOCK

Opening a file or device.OPEN

Closing a file or device.CLOSE

In a Use command.USE

Reading from a file or device.READ

Writing to a file or device.WRITE

Retrieving a value from a global.GGET

Setting a value into a global.GSET

Killing a global/node.GKILL

Executing $order.GORDER


Managing Caché

ProcessState

Executing $query.GQUERY

Executing $data.GDEFINE

Calling out from Caché.ZF

Suspended (by the Caché Hang command).HANG

Executing a process initiated by the Job command.JOB

Examining the state of another running process.JOBEXAM

Broadcasting a message to other processes.BROADCAST

Suspended (through user interaction using JOBEXAM).SUSPEND

Executing $increment.GINCR

Setting bit strings in a global (Set $bit).GBITSET

Retrieving bit values from a global.GBITGET

Executing Caché code other than global module or I/Ocommands.

RUN

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 theselected process.



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 toinvestigate, or if a more important process is trying to run and needs the CPU cycles. Fromthe Control Panel:



3. Click Suspend on the shortcut menu.

You may resume a suspended process at any time by clicking Resume from the same shortcutmenu.


Managing Caché

8.1.3.2 Terminate a Process

You may want to terminate a process if it becomes unresponsive or is affecting other processesor users. From the Control Panel:



3. Click Terminate on the shortcut menu.

4. Click Yes to confirm that you want to terminate the process. There is no way to resumea terminated process.

8.1.4 Debug a Process

Caché allows you to access the Debug utility using the Control Panel. This provides you withthe tools needed to debug a process or a routine you have started as a process.



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 theCommand-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 pro-cesses. These utilities are useful for asking people to sign off the system. However, you mustuse them carefully or you may cause messages to appear in the middle of reports that maybe printing at the time.

The utility temporarily takes control of each terminal as it sends the message. Once the terminalreceives the message, the previous job continues. The message will appear on the terminalscreen; it may disrupt the screen display, but it does not affect user input. The message doesnot appear in windows running Caché utilities.



To broadcast a message to the terminals associated with a selected process, from the ControlPanel:



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 processis automatically displayed in the text box. If you want to broadcast to all processes, clickthat 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 onlyavailable 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.


Managing Caché

Local Databases Information


The database name.Database

The system directory in which the database resides.Directory

The status of the directory, which indicates if the databaseis mounted.

Status

The current allocated size of the database, in bytes.Cur Size

The percent of the currently allocated database size that isin use.

Cur % Full

The maximum size allocated to which the database can grow.Max Size

The percent of the maximum size allocated that is in use.Max % Full

Indicates whether the database is mounted as part of acluster.

Clustered

The block size of the database.Block Size

Indicates whether the database is read-only.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. Thisutility is called %FREECNT. Its output shows the free space available within a database:

USER>Do ^%FREECNT # of Free Free data Expansion blocks blocks blocks available Directory

128 107 83.6% 93 72.7% *** 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.


Monitoring Locks

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


The locked variable.Item Locked

The process ID of the process holding the lock.Process

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 aprocessing transaction.

Exclusive

The lock count for the shared lock mode.Shared

The total number of jobs that are waiting for this lock.Waiters #

The lock attributes.Flags

For a more in-depth description of the Lock command and its features, see the Lock entryof the Caché ObjectScript Reference guide.

You may need to enlarge the size of the lock table if your system uses a large number oflocks:

1. Click the Advanced tab of the Configuration Manager.

2. Expand the Memory branch.


Managing Caché

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 (inbytes), 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 upthe value to the next multiple of 64 KB. The default range is from 65536–1769472.

5. Click OK on the Configuration Manager to change the configuration. Click Restart torestart 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 networkerrors through an operator console facility. For Caché Windows-based systems, there is nooperator console as such and all console messages are sent to a log file, cconsole.log, in thesystem manager namespace, typically CacheSys\Mgr. For Caché systems on UNIX orOpenVMS platforms, you can send operator console messages to the console log file or theconsole terminal.

The console log file is a plain text file and may be viewed with any editor or text viewerincluding 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:


Monitoring Log Files

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


Managing Caché

9Achieving High Availability

This chapter provides an overview of the mechanisms that Caché provides to maintain ahighly available and reliable system. It describes strategies for recovering quickly from systemfailures 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 tosystem crashes. Caché backup and journaling systems provide rapid recovery from physicalintegrity failures. These utilities can be used while applications are running and the databaseis being updated. Logical database integrity is ensured through transaction processing state-ments 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 crashand the database is corrupted. It minimizes the risk of these files also beingcorrupted, increasing the opportunity for successful recovery.


9.1 Surviving a Crash

Both internal and physical integrity can be threatened by hardware failures caused by mal-functions or external events such as fire or loss of electric power. However, modern hardwarehelps avoid system crashes, and Caché contains safeguards and offers strategies that allowyou to recover data as quickly and completely as possible.

Two mechanisms critical to the recovery process are write image journaling and establishinga consistent journaling and backup strategy.

9.1.1 Write Image Journaling

Write image journaling maintains the internal integrity of the Caché database, and is thefoundation of the database recovery process. Write image journaling is automatically enabledwhen you start Caché, and works for all Caché directories.

Rather than writing directly from memory to the database, the Caché Write daemon systemprocess (WRTDMN) uses an intermediate file, the write image journal. This file is usuallynamed cache.wij. On UNIX systems, you may specify a UNIX raw partition in your systemconfiguration.

Write image journaling technology uses a two-phase process of writing to the database, asfollows:

• In the first phase, Caché records the changes needed to complete the update in the writeimage journal. Once all updates to the write image journal have been entered, a flag isset in the file and the second phase begins.

• In the second phase, the Write daemon writes the changes recorded in the write imagejournal to the database on disk. When this second phase completes, the Write daemonsets 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 pro-cedure if it detects that an abnormal shutdown occurred. When Caché indicates successfulcompletion, the internal integrity of the database is restored.

Recovery is necessary if a system crash or other major system malfunction occurs at eitherof 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.


Achieving High Availability

• After the update to the write image journal is complete but before the update(s) to thedatabase is complete. In this case, recovery rewrites the updates from the write imagejournal file to the database.

Note: The two-phase write protocol safeguards structural database integrity, but it doesnot prevent data loss. If the system failure occurs prior to a complete write of anupdate to the write image journal, Caché does not have all the information it needsto perform a complete update to disk. That data is lost.

9.2 Backup Strategy

The best and most common strategy for backing up Caché databases is to perform daily onlineconcurrent backups during the slowest period of a production day. You do not have to stopCaché to back up your data.

Caché maintains a bitmap list of database blocks modified since the last backup; you can usethis list to keep track of database updates during backup stages. The DBSIZE utility, whichinspects these bitmaps, helps you calculate the size of a backup. Caché BACKUP uses amultipass scan of these lists to back up only the blocks modified since the last pass. Subsequentpasses usually operate on a reduced list of modified blocks; generally three passes are sufficientto complete a backup. During the final pass, Caché suspends all processes to prevent updatesand allow the backup to completely copy the last short list of modified blocks. This methodis 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, preferredbackup 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 ResponseCenter.


Backup Strategy

9.2.1 Concurrent External Backup

A concurrent external backup, or “dirty backup,” is the most common strategy used by large-scale 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 backupdepends on your preference and the operating system. You may choose a native operatingsystem utility, such as the tar utility on UNIX, or a third-party utility such as Veritas orARCserve. Caché makes it easy to integrate with such utilities. The following is an exampleof a UNIX procedure:

1. Clear the list of database blocks modified since the last backup. This synchronizationpoint later allows you to identify all database blocks modified during the backup. Callthe application program interface (API), CLRINC^DBACK("QUIET"), in the backupscript; 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. Thisshould be an output sequential file. Since it is likely to be a small set of blocks, this stepshould 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 << cleanups 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 strategyused by large-scale production facilities that have large databases and limited time to completea backup, but can tolerate a brief operational pause. This strategy is often used in conjunctionwith advanced disk technologies, such as disk mirroring. The approach is to safely pauseCaché long enough to separate a mirror copy of data and then quickly allow Caché to continue



processing. You back up the mirror and then later rejoin it to the production disk(s) and catchup. Caché makes it easy to integrate in this configuration:

1. Switch the journal file using the Control Panel, JRNSWTCH, or the APIINT^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 completetheir work by setting a software switch that inhibits activity and waiting for all processesto 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 thesoftware 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 withoutinterrupting Caché processing; for example, if daily incremental backups are performed ratherthan 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 blocksin use, an incremental backup of only the blocks modified since the last incrementalbackup, or a cumulative, incremental backup of the blocks modified since the lastfull backup.

9.2.4 Cold Backup

The cold backup strategy is generally used in the rare case when the operation toleratesdowntime. Sometimes, this is done only when performing a complete system backup as partof a maintenance effort such as repairing faulty hardware. In this situation, stop Caché duringthe 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.


Backup Strategy

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 typeof application integrity is called logical integrity. Caché protects the logical integrity ofdatabases using the following:

• Transaction Processing

• Transactions and Locking

• Global Journaling

For more information, see the “Transaction Processing” chapter of Using Caché ObjectScriptand 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'smedical record, transferring funds from one bank account to another, and reserving an airlineseat.

In general, you must define the scope of a transaction although Caché can infer the boundariesin 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 logicalor application-level integrity. It does not prevent you from ending up with half of a patientrecord or two-thirds of airline seat processing.

The best protection is offered by transaction processing. In a Caché application, the start ofa unit of work is indicated with a TStart command. If the transaction completes normally, aTCommit command is issued. If a transaction does not complete successfully, Caché performsa process called rollback, in which all values altered by the transaction are restored to theirprior 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 donefrom an application error-handling routine following an error. You can use CachéObjectScript to implement these techniques in your application, or rely on automatictransaction processing in Caché SQL.



• 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 hardwarefailure, 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 astarting balance of $1,000, to a checking account with a balance of $500. Without transactionprocessing, there are two journal entries:

SET SAVINGS 900SET CHECKING 600

Now suppose that transaction processing is invoked by preceding these updates with a com-mand to begin the transaction, and following them with a command to commit the transaction.In this case, the journal conceptually contains:

STARTSET SAVINGS 900OLD SAVINGS 1000SET CHECKING 600OLD CHECKING 500COMMIT

In addition to the new values of 900 and 600, the journal contains the pre-transaction valuesof 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 two-phase write protocol restores the internal consistency of the database. Next, all incompletetransactions (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 todata.

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 recordTCOMMIT


Logical Data Protection

The value of SAVINGS becomes unavailable to other processes when it is locked, and availableagain as soon as it is unlocked.

Now suppose that a transaction fails as the application is updating CHECKING. Transactionrollback occurs, restoring SAVINGS to its pre-transaction value. But, what if between theinstant the application unlocks SAVINGS and transaction rollback completes, another processaccesses SAVINGS? If it examines this value, it may carry out further processing that iserroneous. Worse yet, if it changes this value, rollback cannot occur.

Caché automatically avoids this problem by deferring any unlocks within a transaction untilthe transaction is committed or rolled back. Within the transaction, the data appears to beunlocked, permitting a subsequent lock of the same value in the same transaction to workcorrectly. 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 backupis the cornerstone of physical recovery, it is not the complete answer. Restoring the databasefrom a backup makes the contents of the database current as of the time the backup wascompleted. Typically, this will be a long time (at least a number of hours) before the pointat which physical integrity was lost. What happens to all the database changes that occurredsince then? The answer lies with journaling.

Each computer running Caché keeps a journal. The journal is a file that keeps a time-sequencedlog of changes that have been made to the database since the last backup. The process isredundant and logical and does not use the Caché Write daemon. You can turn on journalingfor all modifications to the database, or enable selectively on a global-by-global basis. Thedefault setting is to journal all globals, except those stored in CACHETEMP. Selective jour-naling avoids the overhead of saving updates to databases or globals for which recovery isnot needed. Caché transaction processing works with journaling to maintain the logicalintegrity of data.

The journal also contains Set and Kill operations for all globals marked for journaling.



When Caché starts, all journal entries since the last Write daemon pass are reapplied. Sinceuser processes update the journal concurrently, rather than through the Write daemon, thisapproach 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 afailure renders your database inaccessible or unusable, you can restore the backups and applythe 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 thesubsequent 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 mechanismcompletes the updates that were in progress. By contrast, other systems employ a “rollback” approach, undoing updates to recover. While both approaches protect internalintegrity, 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 followingrecovery, preceding updates are also present. Other systems which do not correctly pre-


Database Integrity Protection

serve update sequence may yield a database that is internally consistent but logicallyinvalid.

• The incremental backup file structures are protected, as well as the database. A validincremental 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 checkingare 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 checkthe log.

4. From the File menu, you may save the log to a file, print it, or exit the Job Status dialogbox.

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



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, thenclick 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 Întegrity. The name is case-sensitive and you call itfrom the Caché manager's namespace with Do Întegrity. This is the equivalent of runningIntegrity Check on Local Databases from the Control Panel.

There are three additional entry points to this routine:

• Do CheckPointerÎntegrity asks for a directory and a pointer block at which to startchecking.

• Do SilentÎntegrity(logfilename) starts a background job which does an integritycheck 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Întegrity(logfilename,outdevice) does not run an integrity check, butputs the contents of the file specified by the logfilename parameter, the results saved froma previous run, out on the current device or the device specified in the optional parameteroutdevice.

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 selecteddatabases as they are updated on a primary machine. By continually transferring journal


Shadow Journaling

information from the primary machine to the secondary machine, shadow journaling makesit possible to fail over to a database which is within only a few transactions of the primarydatabase.

By itself, shadow journaling does not ensure successful failover, but it is a very simple andinexpensive way to maintain a disaster recovery system. Often, this approach is also used toupdate a report server, where ad hoc reporting tasks can operate on current data withoutaffecting production.

Shadow journaling monitors database activity on a primary system and causes the sameactivity to occur on a secondary system. It does this by means of a shadow client servicerunning on the secondary system that continually requests journal file details from a shadowserver service running on the primary system. The shadow server service responds by sendingthe details of the Set or Kill journal record entry to the secondary system over a TCP connec-tion.

For more detailed information, see the “Shadow Journaling” chapter of the Caché HighAvailability Guide.

9.6 System Failover Strategies

Caché fits into all common high availability configurations promoted by operating systemproviders, including Microsoft, IBM, HP, Compaq, and EMC. Caché provides easy-to-use,often automatic, mechanisms that integrate easily with the operating system to provide highavailability. There are four general approaches, in the order of increasing availability:

• No Failover—for applications that are most likely not business-critical.

• Cold Failover—a common and inexpensive approach that involves switching to a standbysystem in case of a failure.

• Warm Failover—exploits a standby system that is ready to accept users instantly after aproduction system failure.

• Hot Failover—can be complicated and expensive, but comes closest to ensuring 100%uptime.



Failover Strategy Impact

User ImpactExpenseRecovery TimeApproach

HighNo cost to low costUnpredictableNo Failover

ModerateModerateMinutesCold Failover

LowModerate to highSecondsWarm Failover

NoneModerate to highImmediateHot Failover

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 developa failover and backup strategy tailored for your environment, or to review your current backuppractice, please contact the InterSystems Worldwide Response Center.


System Failover Strategies

Documents

Gsa