Skip to main content
Previous section   Next section

Managing Caché Remotely

Routines and utilities for managing Caché from a terminal or an external program.

  • Using ^GBLOCKCOPY for Fast Global Copies — describes a routine that performs fast global copies between databases as well as other useful operations.

  • Using Switches — discusses the available Caché switches, which are per-instance flags that can be used for a variety of purposes. They are especially useful for inhibiting various system processes when doing backups or trying to recover crashed systems.

  • Controlling Caché from a Windows Client — describes a DLL that allows your program to function as a Windows client that can check the status of Caché and perform calls to Caché.

  • Character-based Management Routines — describes two useful terminal routines: ^SHADOW allows you to define and manage a shadow system for another Caché instance, and ^LEGACYNETWORK allows you to list, add, edit, and remove COM ports.

Using ^GBLOCKCOPY for Fast Global Copies

^GBLOCKCOPY is a Caché routine that performs fast global copies between databases. It can be run interactively to a terminal, or be set up in a batch to run one or more global copies as background jobs. ^GBLOCKCOPY contains a built-in monitor and several reports to track the progress of global copies. You can restart ^GBLOCKCOPY at the point it left off if there is a system failure.

This section discusses the following topics:

Note:

The ^GBLOCKCOPY should only be used to copy globals when they are not being actively modified because there is no locking or integrity checking for database blocks that are being copied. Although Set or Kill operations may be performed on other globals in the source database where the copy is being performed, as well as in the destination global, database, or namespace without affecting the copy, results in the destination global are unpredictable if Sets or Kills occur in the source global that is being copied to another database or namespace.

When ^GBLOCKCOPY copies a global to a new database, it creates the global there with the same properties of the source global, including Protection, Journal attributes, Collation type, and Keep attributes. The one exception is if the global has one of the following collations:

  • ISM Pre-6.2

  • ISM 6.2->6.4

  • Ipsum/Cobra

  • Ipsum/Cobra-2

In these cases, the routine automatically changes the collation to Caché Standard.

Note:

In recent releases of Caché, the SYS.Database.Copy() class method provides functionality similar to ^GBLOCKCOPY.

Uses of ^GBLOCKCOPY

^GBLOCKCOPY can be used for several different operations as follows:

  • Copy single or multiple globals from a database to another database or namespace — You can select one or several globals to be copied into a destination database or namespace. If the global already exists in the destination database, data from the source global is merged into the existing data.

  • Split a global from a single database into multiple databases using subscript level mapping — By setting up a namespace with subscript level mapping (SLM) of a global, you can copy a global from a database into this new namespace and cause it to be split amongst the database which make up SLM.

  • Move a subscript-mapped global in many databases into one database — Create a new database which contains the entire global. Then set up several copies in a batch which will copy the global from all the different SLM databases into the new database. Since databases can now exceed 2 GB in size, this is a useful method for consolidating databases.

  • Make a copy of a database — You may copy a database to another directory by copying all the globals to it.

  • Copy a global to another machine across ECP^GBLOCKCOPY supports copying a global across an ECP network connection to another machine. You need to set up an ECP connection to a remote machine, and a namespace mapping which points to it. Then select the “Copy from Database to Namespace” option and select the remote namespace as the destination of the copy.

  • Reclaim unused space in a database — If a large global is created then killed in a database, there may be a large excess of unused space in the database. You can remove this space by copying all the globals in the database to a new one, and then replacing the old database with the new database.

  • Reorganize the pointers in a database — If a database becomes fragmented because of block splits, you may want to reorganize the data in it to speed performance. You can do this by copying all the globals in a database into a new database, and then replacing the old database with the new database.

  • Change the collation of a global — If a source global is of any of the following collation types:

    • ISM Pre-6.2

    • ISM 6.2->6.4

    • Ipsum/Cobra

    • Ipsum/Cobra-2

    The collation of the global is automatically changed to Caché Standard if it is copied via ^GBLOCKCOPY.

    If you have an existing global which you want to change the collation of (for example, from Caché Standard to German1), create the global in the destination database with the correct desired default collation before running ^GBLOCKCOPY.

    Note:

    Databases which migrated from ISM 5.10/6.4 will contain globals with ISM collations.

  • Import a legacy database into a CACHE.DAT database or namespace — If you have a legacy database file which you want to import to a CACHE.DAT database or namespace, simply select the directory where it exists as the source directory as the copy. The database is renamed CACHE.DAT, and the data is available to copy to the destination database or namespace.

  • Import a ISM 5.10/6.4 MUMPS.DAT database into a CACHE.DAT database or namespace — If you have a MUMPS.DAT file which you want to import to a CACHE.DAT database or namespace, simply select the directory where it exists as the source directory as the copy. The database is renamed CACHE.DAT, and the data is available to copy to the destination database or namespace.

Running ^GBLOCKCOPY

Before you run ^GBLOCKCOPY (or for that matter before you perform an upgrade), make a full operating system backup of your databases, and run an integrity check to ensure there is no corruption in any of the databases.

Note:

To make ^GBLOCKCOPY run faster, kill off any temporary and scratch data as well as any old data you do not require.

You can use the batch functionality of ^GBLOCKCOPY to set up a batch of operations to run at the same time. While the batch of operations is running, you can monitor progress using the Monitor or Batch Report.

Note:

Users should be kept from accessing the databases while they are being processed by ^GBLOCKCOPY. The result of the database operations are unpredictable if they are accessed while ^GBLOCKCOPY is running. Databases on the same system which are not being processed by ^GBLOCKCOPY can be used safely.

Using Switches

Caché switches are per-instance flags that can be used for a variety of purposes. They are especially useful for inhibiting various system processes when doing backups or trying to recover crashed systems. The ^SWSET routine is used to directly manipulate the values of the switches.

Background

Switches in Caché have their genesis in the physical contacts once part of computer operator consoles or included in the front panel of microcomputers. By setting one of these switches, an operator could convey a single bit of information to the programs running on the machine at that time. Since Caché implements a “virtual machine”, the concept of the switch for this machine has been similarly abstracted.

Today, switches in Caché are represented as individual bit settings in the shared, common memory of a Caché instance; they are visible to all Caché processes. While several have been set aside for users, most influence the operation of Caché itself.

Note:

Users should view the switches as being local to a Caché instance. Although Caché itself provides mechanisms to propagate the meaning of certain settings to other members of a cluster or ECP configuration, these are for InterSystems internal use only. The values of the user switches cannot be moved to other systems.

Currently Defined Switches

All switches are identified by number. They are initialized to zero (off) when Caché starts. The following table gives the switch number(s) and their effect:

Switch Meaning / Use
0 — 7 Reserved for use by applications programs.
8 Inhibits existing Caché daemons from responding to network requests.
9 Inhibits the creation of new daemons to process network logins.
10 Inhibit all global access except by the process that sets this switch. Also inhibit routine accesses that causes disk IO except for this process.
11 Inhibit all global access except for the system job that sets this switch. This overrides switch 10 and is reserved for use by the system. This switch is set, for example, by the backup process to quiesce system activity before copying.
12 Inhibits the ability to login to Caché. Users who attempting to login will receive a message: "Sign-on and JOB inhibited: Switch 12 is set".
13 Inhibits all global SETs, KILLs and ZSAVE commands; only read access is allowed to globals and routines.
14 Inhibits all access to all globals and all routines.
15 Allow network references from peers, even if switch 10,13, or 14 would normally prevent the access.
16 Used internally by Caché to coordinate shutdown activity.
17 Bypass wait for completion of journal flush on clusters.
18 Inhibits pausing added processes if the queue for a block gets too long.
19 Inhibit the start of new transactions.
20 — 31 Undefined and reserved for InterSystems use.
Caution:

Customer applications should confine any switch activity to the set reserved for applications programs (switches 0–7), except when specifically directed otherwise by InterSystems personnel or its documented procedures.

Manipulating Switches

The ^SWSET routine is used to directly manipulate the values of the switches. In addition, other Caché facilities, such as those that work with journals on clustered systems and system backup, also set them on behalf of their callers.

Routine SWSET

This routine provides an interactive way to set the value of the switches from, for example, a terminal session.

SWSET
Parameters

None.

Remarks

When invoked as in the example below, the routine will prompt for the switch number and then prompt for the value to be set in the switch (0 or 1).

Examples

The following example demonstrates the use of SWSET . After executing

    DO ^SWSET
Copy code to clipboard

the user will successively see the following:

Set/Clear switch #:

Set/Clear switch #: 2

Set/Clear switch #: 2 to value (0 or 1):

Set/Clear switch #: 2 to value (0 or 1): 1

Set/Clear switch #: 2 to value (0 or 1): 1...done

Function %swstat^SWSET

This function returns the current setting for the switch.

%swstat^SWSET(switch)
Parameters
  • switch — The number of the switch.

Remarks

If the switch is a valid number, this function returns the value of the switch as one of the following:

  • 0 — the switch is reset (off)

  • 1 — the switch is set (on)

otherwise it returns a value of –1 indicating that an error has occurred.

Examples

The following example prints the value of switch number 1.

   Write $$%swstat^SWSET(1)
Copy code to clipboard

Function %swset^SWSET

This function sets the switch to the specified value.

%swset^SWSET(switch, value)
Parameters
  • switch — The number of the switch.

  • value — The value it should have, 0 or 1.

Remarks

There are three possible returns:

  • 0 — Indicates the switch was not set to its intended value.

  • 1 — Indicates the switch was properly set to its new intended value.

  • -1 — Indicates the switch was set to an impossible value (something other than 0 or 1).

Examples

The following example sets the value of switch number 1 to off.

   Write $$%swset^SWSET(1, 0)
Copy code to clipboard

Failure Modes

A Caché process which sets one of the system-reserved switches and terminates without properly cleaning up its work can leave the system in a restricted operating mode. For example, a process that sets switch 12 and then suffers a catastrophic failure (or even merely HALTs) will leave Caché in a state where no further users can login. If this situation occurs, the administrator or operator is urged to call the InterSystems Worldwide Response Center (WRC).

Note:

The only situation for which Caché implements an automatic recovery is for switch 10. If a process sets this switch and then HALTs, Caché will automatically reset the switch to zero.

Controlling Caché from a Windows Client

This section details usage of a dll to check the status of Caché and perform calls to Caché from a Windows client.

Caché provides a mechanism for Windows client programs to control a Caché configuration and to start up Caché processes. This allows you to deliver applications that automatically start Caché processes with the correct configuration information without requiring the standard Caché tools. The tools allow you to:

  • Find Caché directories paths and service name for a given configuration name.

  • Get the status of the Caché system.

  • Control a Caché configuration directly or through the Caché Control Service, depending on which version of Windows is running

  • Start a Caché process with the appropriate settings.

Caché provides sample programs in C, C++, and Visual Basic that demonstrate dynamic loading of cctrl.dll and use of the functions to start, stop, and force a configuration, and to start Caché processes. These samples are located in the Dev/cache subdirectory of your Caché installation.

  • cctrlcpp — C++ code sample

  • cctrlvb — Visual Basic code sample

  • ctrldemo — C code sample

CctrlGetDirs

Finds configuration, binary, and manager directory paths, and service name for a given configuration name.

Syntax
CctrlGetDirs(char *config, CCTRL_DIR_INFO *dirinfo)
Copy code to clipboard
config The name of the desired configuration.
dirinfo A pointer to a C structure where the directory information will be stored.
Return Values

Returns (char *0) on ERROR.

CctrlConfigStatus

Returns the status of the Caché configuration.

Syntax
CctrlConfigStatus(char* config)
Copy code to clipboard
config The name of the desired configuration
Return Values

Returns a value from 0 through 4 as follows:

0 Configuration is up and running.
1 Configuration is starting or stopping.
2 Configuration startup or shutdown aborted.
3 Configuration is down.
4 ERROR

CctrlControl

Controls a Caché configuration through the Caché Control Service on Windows NT, or directly on Windows 95/98.

Syntax
CctrlControl(char *command, char *config)
Copy code to clipboard
command Use one of the following commands:
  • start — starts a configuration
  • stop — shuts down a configuration gracefully
  • stopnoshut — shuts down a configuration without running the user-supplied shutdown routine
  • force — forces down a configuration; equivalent to cforce on UNIX® systems
  • stopstart — shuts down a configuration gracefully and immediately restarts it
config The name of the desired configuration.
Return Values
CCTRL_SUCCESS Operation succeeded
CCTRL_ERROR Generic error
CCTRL_INVALID_COMMAND Invalid command argument
CCTRL_INVALID_CONFIGURATION Undefined configuration
CCTRL_CONTROL_STU_ERROR ^STU failed

Following an error return, CctrlGetLastError returns a pointer to an informational error string.

CctrlRun

Starts a Caché process in the indicated configuration, and namespace, using the indicated principal I/O device and invoking the indicated routine.

Syntax
CctrlRun(char *config, char *routine, char *namespace, char *IOtype)
Copy code to clipboard
config The name of the running configuration.
routine The name of the desired routine to start.
namespace The name of the desired namespace.
IOtype How I/O is to be handled, which can have a value of either cterminal or none.
  • cterminal — Caché programmer’s terminal.
  • none — No I/O. Process will run in the background with NUL: used for $Principal. Writes to $Principal are discarded. Reads from $Principal produce an error.
Return Values
CCTRL_SUCCESS Operation succeeded
CCTRL_ERROR Generic error
CCTRL_INVALID_COMMAND Invalid command argument
CCTRL_INVALID_CONFIGURATION Undefined configuration
CCTRL_CONTROL_STU_ERROR ^STU failed
Note:

On Windows NT, the specified configuration must be running. If you are not sure if the configuration is running, use CctrlConfigStatus and CctrlControl to check and start the desired configuration. This prevents Caché from trying to start a configuration without using the control service.

CctrlRunIO

Starts a Caché process in the indicated configuration, and namespace, using the indicated principal I/O device type, invoking the indicated routine and additional IO specifications for input, output and error devices.

Syntax
CctrlRunIO(
        char *config, 
        char *routine, 
        char *namespace, 
        char *IOtype, 
        HANDLE *hIO, 
        char *cwd, 
        char *options, 
        HANDLE *child, 
        DWORD *childPID))
Copy code to clipboard
config The name of the running configuration in all capital letters.
routine The name of the desired routine to start.
namespace The name of the desired namespace.
IOtype How I/O is to be handled, which can have a value of TCP, cterminal, or none:
  • TCP — TCP socket.
  • cterminal — Caché programmer’s terminal.
  • none — No I/O. Process will run in the background with NUL: used for $Principal. Writes to $Principal are discarded. Reads from $Principal produce an error.
hIO An array of three handles to be used as the standard input, output, and error devices of the Caché process.
cwd The working directory path of the child process. If the directory argument is zero, the working directory of the current process is used.
option Additional cache.exe command line options appended to the generated command line. For example, you could define a larger process memory size (-b 1024).
child The pointer to a variable of type HANDLE, where the handle to the child process will be returned. If the value of handle is zero, the handle to the child process will be closed by this function.
childPID The pointer to the PID of the created cache.exe process. This argument can be zero if the child’s PID is not required.
Return Values
CCTRL_SUCCESS Operation succeeded
CCTRL_ERROR Generic error
CCTRL_INVALID_COMMAND Invalid command argument
CCTRL_INVALID_CONFIGURATION Undefined configuration
CCTRL_CONTROL_STU_ERROR ^STU failed
Note:

The handles in the hIOarray must be inheritable. Use DuplicateHandle to make the handle inheritable by the child process.

On Windows NT, the specified configuration must be running. If you are not sure if the configuration is running, use CctrlConfigStatus and CctrlControl to check and start the desired configuration. This prevents Caché from trying to start a configuration without using the control service.

Character—based Management Routines

The preferred and recommended way to manage a Caché installation is the Management Portal. The portal provides a convenient, browser-based interface for controlling the system. However, to cover those instances when the system cannot be managed this way, Caché has several character-based routines that can provide some important functions from the Terminal.

The utilities described in this section are:

  • ^SHADOW — allows an administrator to define and manage a Caché instance serving as a shadow system for another Caché instance.

  • ^LEGACYNETWORK — allows an administrator to list, add, edit, and remove COM ports. .

Each of the routines is described in its own section along with its top-level functionality. In most cases, the initial menu choice will lead to further requests for information until the routine has sufficient information to accomplish its task. To use any routine from the Terminal, the user must be in the %SYS namespace and have at least the %Manager role. The routine (for example ^SHADOW) is invoked as expected with the command:

 DO ^SHADOW
Copy code to clipboard

When the routine runs, it presents you with a list of options. Select an option by entering its number after the “Option?” prompt.

Caution:

As previously noted, the preferred way to manage a Caché system is via the Management Portal. Administrators who elect to use the routines described in this documents are assumed to have a detailed operating knowledge of how Caché works and what parameter values are appropriate for the options they choose.

General notes about prompts

The following are characteristics of prompts when using the character-based facilities:

  • Each option has a numeric prefix. Select an option by typing its number. The option-number pattern is used throughout the routines.

  • All option lists have an item to exit this level of menu and return to the previous level. You may also reply to the “Option?” prompt with Enter. This is interpreted as if you had chosen the “Exit” option, that is, you are finished with that section and you are presented with the next “upper” level of options. An Enter reply to the top-level of options exits the ^SHADOW routine.

  • Many of the prompts for information have a default value which is selected by typing the Enter key. When there is a default value available, it is shown after the prompt message and followed by the characters “=>” as in

    Unsuccessful login attempts before locking user? 5 =>
    

    where the default value is 5 for the number of times a user may try to login and fail before the system locks their username.

  • Prompts whose defaults are “Yes” or “No” also accept any matching partial response such as “yE” or “n”. The match is done ignoring the case of the response.

  • In options whose intent is to alter the characteristics of existing user, roles, services, and so on, the existing value of the item is displayed as the default. Typing Enter preserves that value and moves on to the next prompt.

  • Some prompts ask for a pattern to use when matching items such as usernames. The default pattern is usually “*” that matches all items. In such patterns the asterisk matches any sequence of characters, much like it does in DOS. A pattern may also consist of a comma-separated list of items each of which is treated as its own pattern. An item is treated as being selected if it matches any pattern in the list.

Caution:

There is nothing to prevent multiple instances of the same routine from being executed at the same time by different system administrators (or even the same administrator). If this happens, it is the responsibility of the administrators to coordinate their activity to avoid conflicts and achieve their objectives with regard to the coherence of the affected data.

^SHADOW

This routine allows an administrator to define and manage a Caché instance serving as a shadow system for another Caché instance.

  1. Create a shadow

    Lets you specify the parameters needed to identify another system as the shadow server for this one.

  2. Edit a shadow

    Lets you change the parameters associated with an existing shadow.

  3. List shadows with properties

    Lists the systems defined as shadow servers along with their properties.

  4. List shadows with running stats

    Lists the systems defined as shadow servers along with their performance information.

  5. Start a shadow

    Initiates shadowing with a defined server.

  6. Stop a shadow

    Stops the shadowing activity.

  7. Suspend a shadow

    Pauses the transmission of data to a shadow server.

  8. Resume a shadow

    Resumes shadowing activity with a previously suspended server.

  9. Restart a shadow

    Begin shadowing again with a defined server.

  10. Delete a shadow

    Removes a system from the list of known shadow servers of this system.

  11. Show detail of a shadow

    Shows all the information on a particular shadow server.

^LEGACYNETWORK

This routine supports configuration of legacy networking tools that are available for use with Caché.

  1. COM Port Setup

    Allows you to list, add, edit, and remove COM ports (serial COMmunications ports). Adding and editing COM ports involves specifying various configuration parameters for them.

  2. Exit