Using ^%IS

Device Prompt

When you call the ^%IS utility, InterSystems IRIS prompts for a device name. You respond in one of the following ways:

• Enter the desired device name or ID number.

• Enter a mnemonic for the device.

• Press Enter to select the current device.

^%IS responds as follows:

• If you enter a device mnemonic, ^%IS finds the corresponding device in the ^%IS global and opens it.

• If you enter a device name, ^%IS issues an OPEN command to that device.

• If the device is an InterSystems IRIS device ID, ^%IS checks the device table to see if that number is remapped to another actual device number. ^%IS then issues an OPEN for the device.

See the discussion “Alternate Devices” that is part of ^%IS Mnemonics section below for information about using alternate devices.

Additional Questions

If the device you specify is a terminal, the utility prompts you with a default right margin. Press Enter to select that margin or type a different value. If a program later attempts to write past the specified right margin, the operating system inserts a “CR LF” (carriage return and line feed) when the margin is reached. If you select a device other than a terminal, the utility asks other types of secondary questions.

Examples

In the following example, the user presses Enter to specify the terminal. The utility prompts for a right margin, suggesting a default value of 80. At the => prompt the user enters 132 as the new margin setting.

%SYS>DO ^%IS
Device: <RETURN>
Right margin: 80 => 132
%SYS>

^%IS Sets the Variable IO and Returns Values of Other Variables

When you select a device, ^%IS sets the variable IO to the device name or number used in the OPEN command. ^%IS also returns the values of the variables listed in the following table:

OPEN Parameters

By default, the OPEN command uses the specifications for the device defined in the ^%IS global. You can override these settings by specifying other settings when you use ^%IS.

Issue a USE Command

After running ^%IS, the application must issue a USE command to the device opened by ^%IS. You can use the variable IO, as long as you understand that its value changes every time you call ^%IS. Then, subsequent InterSystems IRIS I/O commands, such as READ and WRITE, refer to that device.

Issue a CLOSE Command

The user or application developer must close devices opened with the ^%IS utility.

Device Mnemonics

It is useful to have mnemonics for the various devices and, in some cases, to have more than one mnemonic for a single device. Multiple mnemonics allow you to specify different device characteristics for the device and vary characteristics according to the manner in which the device is used. For example, a terminal that is normally used for data entry, and thus has the characteristics of a terminal, may have an auxiliary printer attached. By assigning a different mnemonic that opens the same device with different characteristics, you can treat the terminal/printer combination as a printer when you want hard copy.

You can configure device mnemonics and characteristics using the Management Portal. To learn how to define and activate mnemonic spaces, see the section Defining Default Mnemonic Spaces.

Default Mnemonics

The ^%IS global is initialized at installation with several default mnemonics. For instance, there are two default mnemonics, SPOOL and 2, for the InterSystems IRIS spooler. Simply type “2” or “SPOOL” to send output to the InterSystems IRIS spooler.

If you are logged in on an RT:, LT:, or VT: type device, and your terminal is the current device, ^%IS will accept 0, “”, or the value of IO in response to the “Device” prompt. It will use the appropriate template (RT0:, LT0: or VT0:) for your terminal type to generate the information for your terminal.

Alternate Devices

If users enter an “A” at the Device prompt, output goes to the alternate device defined for the current device. Usually, users expect the alternate device to be a printer. Instead of defining a separate alternate device for each device in the system, you can create a device, pointing to a printer, with the mnemonic “A”. Then, when users enter “A” at the ^%IS “Device” prompt, output goes to that device.

CURRENT^%IS Entry Point

CURRENT is an internal entry point within the ^%IS utility that you can use to obtain the device parameters of the current device. This call to ^%IS returns the values of different variables, so you can keep one set of parameters for your principal device and a different set for a device with different characteristics. Ordinarily, you make a call to this internal entry point when you log in, to allow the application access to the device characteristics of the principal device. CURRENT^%IS returns the values of the variables listed in the table below:

Example

After calling CURRENT^%IS, set $X and $Y to DX and DY to position the cursor.

  DO CURRENT^%IS
  WRITE *27,*61,*DY+32,*DX+32 
  SET $X=DX,$Y=DY

IN^%IS Entry Point

IN is an internal entry point within ^%IS that can be called by routines that only plan to do input from the device. This entry point can be used to ensure that you do not select an output-only device such as a printer.

%SYS> Do IN^%IS

Device: 3 
Right margin: 132= <RETURN>
[you can't read from this device] 
Device: <RETURN>  
Right margin: 80= <RETURN>
%SYS>

OUT^%IS Entry Point

OUT is an internal entry point within ^%IS that can be called by routines that only plan to do output to the device.

Spooling

InterSystems IRIS spooling is independent of the spooling performed by your operating system. Spooling in InterSystems IRIS is a technique that lets you automatically save the output of a program in a global instead of printing it immediately. You can print the output later by sending the contents of the global to the printer.

The mnemonic SPOOL is a default mnemonic. To specify spooling, enter “SPOOL” in response to the Device prompt. The system then asks for a spool file name and description. This is a named used in the ^SPOOL global—not a separate file name at the operating system level.

If any existing file names start with or match the name you specify, they are displayed, and you are asked to choose one. If you select none of the existing files, the system allows you to create a new file with the specified name and description as shown in the following example:

Device: SPOOL
Name:TEST
1. 1 TEST 02 Nov 1999 10:17 am First test 
2. 2 TEST 02 Nov 1999 10:18 am Second Test 
Select one: <Return> not found
Create new document 'TEST'? Yes => yes
Description: Third Test

If you reselect an existing document because you would like to continue adding to an existing file, the system gives you the following options:

1. Add to the very end of the file;

2. Restart at the top of the last page, in which case the lines that will be deleted are displayed on the screen;

3. Restart at page 1 (the beginning).

You can pass the variables listed in the table below to ^%IS when you call it for spooling.

Further Features of ^%IS

^%IS can also be used to perform the following tasks:

• Right margin suppressing—It is possible to set up a terminal line so that whenever that device is selected, the Right margin question is suppressed; the default value is automatically assumed.

• Automatic device selection—If the variable IOP exists when the ^%IS utility is called, the utility automatically tries to open that device rather than ask for a device. If ^%IS is unsuccessful, it sets the variable POP to 1.

• Preconfigured terminals—Using the Management Portal, you can configure a device that does not request any device information from the user.

Contents of Node 0

Node 0 contains the Device panel Location value:

^%IS(mnemonic,0) = Location

Contents of Node 1

Node 1 contains the other Device panel field values separated by a caret (^):

^%IS(mnemonic,1) = Device #^Type^Subtype^Prompt code^not used 
^Other Open parameters^Alternate device

In this example, the device with the mnemonic name 2 (which is a default name for the InterSystems IRIS spooler) has a device number of 2, device type of SPL (spool), device subtype of PK-DEC. The other values are not defined for a spool type device.

^%IS(2,1) = 2^SPL^PK-DEC^^^^^