Skip to main content

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

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)

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.

Feedback