Skip to main content
Previous sectionNext section

Managing InterSystems IRIS Remotely

This chapter describes routines and utilities for managing InterSystems IRIS from the Terminal or an external program, including:

  • Using ^GBLOCKCOPY to perform fast global copies between databases as well as other useful operations.

  • Using the available InterSystems IRIS 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.

  • Using a DLL that allows your program to function as a Windows client that can check the status of InterSystems IRIS and perform calls to InterSystems IRIS.

  • Using character-based management routines that can be invoked in the InterSystems IRIS terminal to manage the instance when the Management Portal cannot be used.

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:

  • 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 you want to change the collation of an existing global you are copying, you can create the global in the destination database with the desired default collation before running ^GBLOCKCOPY.

  • Import a Caché or legacy database or namespace into InterSystems IRIS — If you have a CACHE.DAT file or legacy database file you want to import to an IRIS.DAT database or namespace, simply select the directory where it exists as the source directory for the copy. The database is renamed IRIS.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

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

There are three possible return values:

  • 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 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

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:

  • 0 — the switch is now reset (off)

  • 1 — the switch is now set (on)

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)
Copy code to clipboard

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:

  • Find InterSystems IRIS directories paths and service name for a given configuration name.

  • Get the status of the InterSystems IRIS system.

  • Control an InterSystems IRIS configuration directly or through the InterSystems IRIS Control Service, depending on which version of Windows is running

  • Start an InterSystems IRIS process with the appropriate settings.

IRISctlGetDirs

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

Syntax
IRISctlGetDirs(char *config, IRISCTL_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.

IRISctlConfigStatus

Returns the status of the InterSystems IRIS configuration.

Syntax
IRISctlConfigStatus(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

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)
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 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)
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, with possible values of:
  • terminal — The process starts a new InterSystems IRIS programmer’s terminal.
  • none — No I/O. The process runs 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))
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 must have a value of TCP, because the process uses a TCP socket.
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
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.

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:

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