Caché Specialized System Tools and Utilities
Managing Caché Remotely
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

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

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:
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:
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
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
Remarks
If the switch is a valid number, this function returns the value of the switch as one of the following:
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)
Function %swset^SWSET
This function sets the switch to the specified value.
%swset^SWSET(switch, value)
Parameters
Remarks
If the switch is a valid number and value is either a 0 or 1, this function sets the switch to that value and returns:
otherwise it returns a value of –1 indicating that an error has occurred.
Examples
The following example sets the value of switch number 1 to off.
   Write $$%swset^SWSET(1, 0)
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:
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.
CctrlGetDirs
Finds configuration, binary, and manager directory paths, and service name for a given configuration name.
Syntax
CctrlGetDirs(char *config, CCTRL_DIR_INFO *dirinfo)
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)
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)
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)
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))
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 Caché Terminal.
The utilities described in this section are:
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 Caché 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
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:
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