docs.intersystems.com
Home  /  System Administration  /  Specialized System Tools and Utilities  /  Managing InterSystems IRIS Remotely


Specialized System Tools and Utilities
Managing InterSystems IRIS Remotely
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


Routines and utilities for managing InterSystems IRIS™ from a terminal or an external program.
Using ^GBLOCKCOPY for Fast Global Copies
^GBLOCKCOPY is an InterSystems IRIS 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:
Because there is no locking or integrity checking for database blocks that are being copied, ^GBLOCKCOPY should be used to copy globals only when they are not being actively modified . 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.
Note:
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
InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS implements a “virtual machine”, the concept of the switch for this machine has been similarly abstracted.
Today, switches in InterSystems IRIS are represented as individual bit settings in the shared, common memory of an InterSystems IRIS instance; they are visible to all InterSystems IRIS processes. While several have been set aside for users, most influence the operation of InterSystems IRIS itself.
Note:
Users should view the switches as being local to an InterSystems IRIS instance. Although InterSystems IRIS itself provides mechanisms to propagate the meaning of certain settings to other members of a cluster, 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 InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS. 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 InterSystems IRIS 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 InterSystems IRIS 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
An InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS implements an automatic recovery is for switch 10. If a process sets this switch and then HALTs, InterSystems IRIS will automatically reset the switch to zero.
Controlling InterSystems IRIS from a Windows Client
This section details usage of a dll to check the status of InterSystems IRIS and perform calls to InterSystems IRIS from a Windows client.
InterSystems IRIS provides a mechanism for Windows client programs to control an InterSystems IRIS configuration and to start up InterSystems IRIS processes. This allows you to deliver applications that automatically start InterSystems IRIS processes with the correct configuration information without requiring the standard InterSystems IRIS tools. The tools allow you to:
InterSystems IRIS provides sample programs in C and C++ that demonstrate dynamic loading of irisctl.dll and use of the functions to start, stop, and force a configuration, and to start InterSystems IRIS processes. These programs are located in the Dev/iris subdirectory of your InterSystems IRIS installation.
IRISctlGetDirs
Finds configuration, binary, and manager directory paths, and service name for a given configuration name.
Syntax
IRISctlGetDirs(char *config, IRISCTL_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.
IRISctlConfigStatus
Returns the status of the InterSystems IRIS configuration.
Syntax
IRISctlConfigStatus(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
IRISctlControl
Controls an InterSystems IRIS configuration through the InterSystems IRIS Control Service on Windows NT, or directly on Windows 95/98.
Syntax
IRISctlControl(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 irisforce on UNIX® systems
  • stopstart — shuts down a configuration gracefully and immediately restarts it
config The name of the desired configuration.
Return Values
IRISCTL_SUCCESS Operation succeeded
IRISCTL_ERROR Generic error
IRISCTL_INVALID_COMMAND Invalid command argument
IRISCTL_INVALID_CONFIGURATION Undefined configuration
IRISCTL_CONTROL_STU_ERROR ^STU failed
Following an error return, IRISctlGetLastError returns a pointer to an informational error string.
IRISctlRun
Starts an InterSystems IRIS process in the indicated configuration, and namespace, using the indicated principal I/O device and invoking the indicated routine.
Syntax
IRISctlRun(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 — InterSystems IRIS 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
IRISCTL_SUCCESS Operation succeeded
IRISCTL_ERROR Generic error
IRISCTL_INVALID_COMMAND Invalid command argument
IRISCTL_INVALID_CONFIGURATION Undefined configuration
IRISCTL_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 IRISctlConfigStatus and IRISctlControl to check and start the desired configuration. This prevents InterSystems IRIS from trying to start a configuration without using the control service.
IRISctlRunIO
Starts an InterSystems IRIS 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
IRISctlRunIO(
        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 — InterSystems IRIS 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 InterSystems IRIS 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 irisdb.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 irisdb.exe process. This argument can be zero if the child’s PID is not required.
Return Values
IRISCTL_SUCCESS Operation succeeded
IRISCTL_ERROR Generic error
IRISCTL_INVALID_COMMAND Invalid command argument
IRISCTL_INVALID_CONFIGURATION Undefined configuration
IRISCTL_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 IRISctlConfigStatus and IRISctlControl to check and start the desired configuration. This prevents InterSystems IRIS from trying to start a configuration without using the control service.
Character-Based Management Routines
The preferred and recommended way to manage an InterSystems IRIS 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, InterSystems IRIS has several character-based routines that can provide some important functions from the Terminal.
Each of the routines is described in its own section along with its top-level functionality. In most cases, the choices on the initial menu choice lead to further menus, or to 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 () is invoked with the DO command. For example, ^LEGACYNETWORK, which supports configuration of legacy networking tools that are available for use with InterSystems IRIS, is invoked with the following command:
 DO ^LEGACYNETWORK
When the routine runs, it presents you with a list of options. Select an option by entering its number after the “Option?” prompt.
Important:
As previously noted, the preferred way to manage an InterSystems IRIS system is via the Management Portal. Administrators who elect to use the routines described in the documentation are assumed to have a detailed operating knowledge of how InterSystems IRIS 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.