Caché System Administration Guide - InterSystems Documentation

1IntroductionThis 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 proceduresand 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

Introduction• Achieving High Availability2 Caché System Administration Guide

Release lever3When the travel lever(3 Figure 5) is released, thedriving clutch is locked. Push on the release lever toallow the machine to move without the engine.1WARNINGAlways use release lever only on flat area. It isdangerous to use release lever on slope whichmakes machine to slip down.Figure 522Fuel cockThe engine is feeded of gasoline when the fuel cock is downwards(Figure 6). The fuel cock is closed when turned to the right.Figure 6Handlebar adjustment :DANGERDo not modify the handlebar adjustment when the machine is inmotion. Perform adjustment only when the machine is on a level flatsurface.Pull the lever rearward to adjust the handlebar (Figure 7) from up and toFigure 7low and from left to right. Check that the lever is locked when theadjustment is performed.Unscrew the lever (Figure 8) to fold the handlebar as required, screwagain the lever to work with the machine.Figure 8Pull the lever backward (Figure 9) to adjust the length of thehandlebar(4 position). Check that the lever is locked whenthe adjustment is performed.Figure 9OREC SP1000 - © SAT 06/20109

Using Caché on WindowsCaché Cube MenuYou 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 CommandsCaché Cube CommandGetting StartedStart CachéStop CachéStudioTerminalFunctionDisplays tutorials, release notes, and documentation.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.Shuts down or restarts the local Caché configuration.Creates, edits, deletes, and compiles Caché classdefinitions, CSP (Caché Server Pages) pages, Caché Basicroutines, and Caché ObjectScript routines. See Using CachéStudio.Invokes the command line interpreter in the Cachéprogramming environment.4 Caché System Administration Guide

Using Caché on Windowsaccess the Bin folder in the Caché configuration directory (CacheSys by default) and doubleclickthe csystray.exe file.Alternatively, you can enter these commands from the /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é configuration.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.6 Caché System Administration Guide

Controlling Caché from the Command Prompt2.4 Controlling Caché from the CommandPromptYou can also control a Caché configuration from the Windows command prompt by runningthe css.exe program in the \Bin directory.Commandcss start css stop css stopnoshut css stopstart css force css [run | console | cterminal]css [run | console | cterminal] css [run | console | cterminal] DescriptionStarts the specified configuration.Shuts down the named configuration.Shuts down the named configuration usingINTNOSHUT^SHUTDOWN.Shuts down and restarts the named configuration.Forces down the named configuration.Runs Caché in programmer mode with either nodevice, the console, or the terminal for $Principal.Runs the named Caché routine in application modewith either no device, the console, or the terminal for$Principal.Runs the named Caché routine in the indicatednamespace in application mode with either no device,the console, or the terminal for $Principal.Caché System Administration Guide 7

3Using Caché on Linux and UNIXThis 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:Caché System Administration Guide 9

Using Caché on Linux and UNIXccontrol start 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 followingmust 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 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.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 procedurequits and Caché continues running.Caché System Administration Guide 11

4Using Caché on OpenVMSThis 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:Caché System Administration Guide 13

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é Instances5.1 Caché InstancesThere 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.Caché System Administration Guide 15

Using Multiple Instances of Caché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 CommandsAction desiredStarting a Caché instanceConnecting to a Caché instanceStopping a Caché instanceCaché commandccontrol start csession ccontrol stop 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é InstanceOnce you have started Caché, run and log on to the Caché shell using the csession command:csession Where configname is the configuration name that you chose during the installation.Caché csession Command and ArgumentsCommandcsession -"B"csession -"U" "namespace"csession "[label[+offset]]^routine"DescriptionProvides system administrator login toperform system tasks such as setting uplicensing.Specifies the login namespace.Runs a routine in user mode.To use application mode or the Caché command line on a remote server use a Telnet client,LAT terminal, or the Caché Terminal.16 Caché System Administration Guide

Controlling Caché Instances5.3 Controlling Caché InstancesYou can control multiple instances of Caché using the ccontrol command. The ccontrolcommand supports a number of functions and has the following syntax:ccontrol [arguments]Caché ccontrol Command and FunctionsCommandccontrol start [args] {configfile}ccontrol stop [args]ccontrol force ccontrol listccontrol allccontrol stat [args]ccontrol help [start | stop | force]ccontrol load *ccontrol unload *ccontrol rename {newname}DescriptionBrings up a configuration.Shuts down a configuration.Forces a configuration down.Lists all installed configurations.Shows compact summary of allconfigurations.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 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 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 availableon Microsoft Windows platforms)Any other value is taken as a .cpf configuration file nameYou 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é InstancesYou 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).18 Caché System Administration Guide

Configuring Multiple Caché Instances• 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 NumbersFor 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/Editto 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 settings.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.Caché System Administration Guide 19

Using Multiple Instances of Caché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.20 Caché System Administration Guide

6Connecting to Remote ServersYou can control remote instances from a Telnet session or from the Remote System Accesssubmenu 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.Caché System Administration Guide 21

Connecting to Remote Servers6.1 Define a Remote Server ConnectionTo 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 FieldsInput FieldServer NameTCP/IP HostPort NumberCommentDescriptionA descriptive phrase that identifies the server; it is what appears asa selection in the Caché Cube.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.The port number of the SuperServer. The default port number is1972.Optional – A description of the remote server.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.22 Caché System Administration Guide

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 ManagersThere 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é topicspecificguides and reference books that you can access from the documentation home page.7.1 Configuring System InformationCaché 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 startsCaché 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 Generaltab 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 DatabasesA 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.24 Caché System Administration Guide

Caché databases dynamically expand as needed, though you can set a maximum limit. Secondaryvolumes 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.Configuring Databases1. 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.Caché System Administration Guide 25

Configuring Caché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.26 Caché System Administration Guide

Configuring Namespaces5. 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 NamespacesA 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 directories,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 NameCaché System Administration Guide 27

Configuring Caché• Modify Database Mapping• Add Global and Routine Mapping to a Namespace• Change the Size of the Namespace Table7.3.1 Create a NamespaceYou 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 NameCaché allows you to change the name of your namespace without requiring a restart.28 Caché System Administration Guide

Configuring Namespaces1. 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 MappingYou 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 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 NamespaceIn 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.30 Caché System Administration Guide

Configuring Namespaces2. 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 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 reservationapplication:Sample Namespace MappingData and programs are stored in Caché databases, the physical storage locations, and referredto by namespaces, the logical references.Caché System Administration Guide 31

Configuring Caché7.3.5 Change the Size of the Namespace TableThe 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 ManagersIf 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.32 Caché System Administration Guide

Configuring License ManagersFrom 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.Caché System Administration Guide 33

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 Files8.1 Controlling Caché ProcessesA 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:Caché System Administration Guide 35

Managing CachéControl Panel FunctionsProcess management functionDisplay process informationDisplay process detailsStopping a processDebug a processBroadcast messages to terminalsMonitoring local databasesMonitoring locksMonitoring log filesHow to access function from the Control PanelClick the Processes task folder.Click Details on the shortcut menu* of the selectedprocess.Click Suspend, Resume, or Terminate as desired onthe shortcut menu* of the selected process.Click Debug on the shortcut menu* of the selectedprocess.Click Broadcast Message on the shortcut menu* ofthe selected process.Click the Local Databases task folder.Click the Lock Table task folder.Click the Logs task folder.* You can access the shortcut menu by right-clicking the selected process in the contentswindow.8.1.1 Display Process InformationTo 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 processeswith statistics about each in columns.36 Caché System Administration Guide

Controlling Caché ProcessesYou 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 InformationColumn HeadingProcessDeviceNamespaceRoutineLines ExecutedGlobal ReferencesLines Executed/ SecDefinitionOperating 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.Caché System Administration Guide 37

Managing CachéColumn HeadingGlobal Refs/SecStateUser NameClient NameExe NameIP AddressDefinitionNumber of global references changed since the last update.Process state. See the Possible Process States table below foran explanation of each state.Name of the user who owns the process.Name of the client system that initiated the process.Name of the executable that called the process.IP Address of the system that initiated the process.* An asterisk (*) appears next to the process id if the user entered Caché in programmer mode.A plus or minus sign appears next to callin processes:• + Process is in Caché• – Process is not in CachéThe callin interface is a Caché SQL facility that lets you execute and evaluate CachéObjectScript commands and expressions from within C programs. You can also use the callininterface from $ZF routines.The following table lists the possible process states as displayed in the process informationtable:Possible Process StatesStateLOCKOPENCLOSEUSEREADWRITEGGETGSETGKILLGORDERProcessPerforming 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é ProcessesStateGQUERYGDEFINEZFHANGJOBJOBEXAMBROADCASTSUSPENDGINCRGBITSETGBITGETRUNProcessExecuting $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/Ocommands.The following codes may be attached to the end of a state:• H — Halting• NH — Network hardening• N — Remote network• W — Hibernating8.1.2 Display Process DetailsYou 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.Caché System Administration Guide 39

Managing Caché8.1.3 Stopping a ProcessYou 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 ProcessYou 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: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 shortcutmenu.40 Caché System Administration Guide

Controlling Caché Processes8.1.3.2 Terminate a ProcessYou may want to terminate a process if it becomes unresponsive or is affecting other processesor 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 resumea terminated process.8.1.4 Debug a ProcessCaché 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.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 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 TerminalsYou 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 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.Caché System Administration Guide 41

Managing CachéTo broadcast a message to the terminals associated with a selected process, from the ControlPanel: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 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 Processestask 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 DatabasesYou can accomplish many database and global management tasks through the Local Databasesfolder 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 LocksLocal Databases InformationColumn HeadingDatabaseDirectoryStatusCur SizeCur % FullMax SizeMax % FullClusteredBlock SizeRead OnlyDefinitionThe database name.The system directory in which the database resides.The status of the directory, which indicates if the databaseis mounted.The current allocated size of the database, in bytes.The percent of the currently allocated database size that isin 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 acluster.The block size of the database.Indicates whether the database is read-only.From this dialog box you can perform various database tasks such as creating, modifying,expanding, and deleting a Caché database.Caché provides an additional tool to monitor the storage growth of your databases. Thisutility is called %FREECNT. Its output shows the free space available within a database:USER>Do ^%FREECNT# of Free Free data Expansionblocks blocks blocks available Directory128 107 83.6% 93 72.7% *** c:\cachesys\mgr\user\8.3 Monitoring LocksCaché 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 InformationColumn HeadingItem LockedProcessExclusiveSharedWaiters #FlagsDefinitionThe 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 aprocessing transaction.The lock count for the shared lock mode.The total number of jobs that are waiting for this lock.The lock attributes.For a more in-depth description of the Lock command and its features, see the Lock 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.44 Caché System Administration Guide

Monitoring Log Files3. 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 MemoryHeap. 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 FilesCaché 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: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. Expandthe General settings branch on the Advanced tab, and update the number of MBs for MaxConsole Log Size.You may also view log information about application errors and ODBC errors.46 Caché System Administration Guide

9Achieving High AvailabilityThis 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 StrategiesCaché 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 statementsand 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.Caché System Administration Guide 47

Achieving High Availability9.1 Surviving a CrashBoth internal and physical integrity can be threatened by hardware failures caused by malfunctionsor 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 JournalingWrite 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 procedureif 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.48 Caché System Administration Guide

Backup Strategy• 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 StrategyThe 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 BackupYou 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.Caché System Administration Guide 49

Achieving High Availability9.2.1 Concurrent External BackupA concurrent external backup, or “dirty backup,” is the most common strategy used by largescaleproduction 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

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.Backup Strategy9.2.3 Concurrent Caché BackupThe 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 BackupThe 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.Caché System Administration Guide 51

Achieving High Availability3. Restart Caché using the ccontrol command or through the Caché Cube.9.3 Logical Data ProtectionApplications 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 JournalingFor more information, see the “Transaction Processing” chapter of Using Caché ObjectScriptand the “Managing Transactions” section in Using Multidimensional Storage.9.3.1 Transaction ProcessingA 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.52 Caché System Administration Guide

• 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 600Now suppose that transaction processing is invoked by preceding these updates with a commandto 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 500COMMITIn 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 twophasewrite 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 LockingYou use the Lock command in Caché applications to protect against simultaneous access todata.For example, an application might contain the following steps:Logical Data ProtectionTSTART//begin transactionLock +^SAVINGS(ACCOUNT,"BALANCE") //lock recordSet ^SAVINGS(ACCOUNT,"BALANCE") = ^SAVINGS(ACCOUNT,"BALANCE") - 100Lock -^SAVINGS(ACCOUNT,"BALANCE") //unlock recordLock +^CHECKING(ACCOUNT,"BALANCE") //lock recordSet ^CHECKING(ACCOUNT,"BALANCE") = ^CHECKING(ACCOUNT,"BALANCE") + 100Lock -^CHECKING(ACCOUNT,"BALANCE") //unlock recordTCOMMITCaché System Administration Guide 53

Achieving High AvailabilityThe 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 JournalingGlobal 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 journalingavoids 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.54 Caché System Administration Guide

Database Integrity ProtectionWhen 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 ProtectionTo 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-Caché System Administration Guide 55

Achieving High Availabilityserve 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 CheckingThe 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 DatabasesYou 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 Statusdialog 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 BackgroundYou 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 CheckYou can view the log resulting from the background job:1. Click View Integrity Log after right-clicking Local Databases.56 Caché System Administration Guide

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.Shadow Journaling9.4.1.4 Check the Integrity of an Individual DatabaseYou 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 UtilityYou can also use the utility routine ^Integrity. The name is case-sensitive and you call itfrom the Caché manager's namespace with Do ^Integrity. 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^Integrity asks for a directory and a pointer block at which to startchecking.• Do Silent^Integrity(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^Integrity(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 JournalingShadow journaling enables a secondary computer to maintain a “shadow” version of selecteddatabases as they are updated on a primary machine. By continually transferring journalCaché System Administration Guide 57

Achieving High Availabilityinformation 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 connection.For more detailed information, see the “Shadow Journaling” chapter of the Caché HighAvailability Guide.9.6 System Failover StrategiesCaché 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.58 Caché System Administration Guide

System Failover StrategiesFailover Strategy ImpactApproachRecovery TimeExpenseUser ImpactNo FailoverUnpredictableNo cost to low costHighCold FailoverMinutesModerateModerateWarm FailoverSecondsModerate to highLowHot FailoverImmediateModerate to highNoneEach 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.Caché System Administration Guide 59