Introduction to the Terminal

User Account That Owns the Terminal Process

The process is owned by the user that is logged in to Windows and is running the Terminal program (iristerm.exe).

Also, all environment variables and shared drive letter designations are those defined by the user that is running the Terminal.

Starting the Terminal

You can use the Terminal interactively or in batch mode.

To use the Terminal interactively, do one of the following:

• To work with the Terminal using a local database, select the InterSystems Launcher and then select Terminal.

• To work with the Terminal using a database on a remote server, select the InterSystems Launcher and then select Remote System Access > Terminal. Then select a server name.

  Or select the InterSystems Launcher, select Remote System Access > Telnet. Then log on with your username and password.

  For more information and additional options, see the chapter “Connecting to Remote Servers” in the System Administration Guide.

• To start the Terminal from Unix, use the following command at the Unix command line: iris terminal instancename.

In either case, you then see the Terminal window. The default prompt displayed indicates the namespace in which you are currently working. For example:

USER>

In batch mode, you invoke the Terminal from the operating system command line, passing to it the name of a script file to run. This mode is not available for all operating systems.

Background

The Terminal was designed to work with InterSystems IRIS® applications. It uses two methods to communicate with InterSystems IRIS: local and network. The title bar indicates the communication mode currently in use.

• Local communication is used when the Terminal communicates with the InterSystems IRIS server with which it was installed. In this case, the title bar displays InterSystems IRIS TRM:pid(instancename) where:

  • pid is the process ID of the InterSystems IRIS process with which the Terminal is communicating.

  • instancename is the InterSystems IRIS instance in which the process is running.

• Network communication uses the TELNET protocol over TCP/IP to communicate with either a Windows InterSystems IRIS server or with a UNIX® host. In this case, the title bar displays (server NT — InterSystems IRIS Telnet) where server is the host name of the remote server.

The communications stack for InterSystems IRIS is Winsock, and errors reported from this communications mode are the names of the Winsock error codes. For example, WSAECONNREFUSED means the connection was refused.

General Use

In the Terminal, you can enter ObjectScript commands of all kinds. The Terminal does not support multiline mode for entering commands, so the entire command must be typed on a single line. For example:

d ^myroutine

set dirname = "c:\test"

set obj=##class(Test.MyClass).%New()
write obj.Prop1

However, you can define multiline routines in the Terminal by executing a series of ZLOAD, ZINSERT, and ZSAVE commands (or using the Tab key shorthand). These routines can then be executed using a DO command.

You can also run Terminal scripts, which are files with the extension .scr existing in your file system. The Terminal provides a small set of commands you can use in these scripts, including a command that sends an ObjectScript command to the Terminal, as if you had typed it manually.

The ZWELCOME Routine

When the Terminal begins execution, the code checks for the existence of a routine called ZWELCOME in the %SYS namespace. If such a routine is found, it is invoked immediately prior to the terminal login sequence, if any. The name of the routine implies its intended use, as a custom identification and welcome message to users.

Here is a simple example:

ZWELCOME() PUBLIC ;
    ; Example
    Write !
    
    Set ME = ##class(%SYS.ProcessQuery).%OpenId($JOB)
    
    Write "Now: ", $ZDATETIME($HOROLOG, 3, 1), !
    Write "Pid/JobNo: ", ME.Pid, "/", ME.JobNumber, !
    Write "Priority: ", ME.Priority, !
    
    Quit

The Startup Namespace

When you start the Terminal, it opens in a particular namespace. This option is controlled by the Startup Namespace option of the user definition. See the chapter “Users” in the Security Administration Guide.

The default prompt displays the current namespace, such as:

USER>

Changing Namespaces

To change to a new namespace, use the $namespace variable:

USER>set $namespace="SAMPLES"
SAMPLES>

See the $namespace reference page in the ObjectScript Reference for more information.

The Terminal Prompt

The default prompt in the Terminal indicates the namespace in which you are currently working. The prompt may display additional information, to indicate the transaction level or the program stack level. If you are using an SQL shell, the MDX shell, or an operating-system shell, the prompt changes. You can also customize the default prompt.

The Transaction Level

If you are within a transaction, the prompt includes a prefix that indicates the transaction level. The prefix is of the form TLn:, where n is the transaction level. For example, if you are in the User namespace and you enter the ObjectScript command TSTART, the prompt changes as follows:

USER>tstart
 
TL1:USER>

If you exit the Terminal, that rolls back the transaction.

The Program Stack Level

If an error occurs, the prompt includes a suffix that indicates the program stack level. For example:

USER 5d3>

Enter the Quit command to exit the debug prompt. Or debug the error; see the chapter “Command-line Routine Debugging” in the book Using ObjectScript.

Operating-System Shells

In the Terminal, you can also open your default operating-system shell. To do so, type ! or $ and press Enter. The Terminal then opens the default operating-system shell, and the prompt shows the working directory. For example:

USER>!
 
c:\intersystems\iris\mgr\user\>

Note:

On Macintosh, you cannot open the C-shell this way; you receive a permission denied error. You can, however, use other shells (Bash, Bourne, or Korn).

To exit the shell, use the quit or exit command as appropriate for the shell.

Interrupting Execution in the Terminal

To interrupt the Terminal and stop any foreground execution, use one of the following key combinations:

• Ctrl+C — Use this if the Windows edit accelerators option is not enabled.

• Ctrl+Shift+C — Use this if the Windows edit accelerators option is enabled.

For information on Windows edit accelerators option, see the section “User Settings,” in the chapter “Controlling the Appearance and Behavior of the Terminal.”

Exiting the Terminal

To exit the Terminal, do any of the following:

• Select File > Exit

• Press Alt+F4

• Enter HALT or H (not case-sensitive)

These options cause this copy of the Terminal to exit, closing any open files and stopping any foreground execution.

If this Terminal was connected to a server at startup, it exits on its own when the communications channel is closed.

If you accessed this Terminal via InterSystems Telnet in the InterSystems Launcher, then it does not exit automatically when the communications channel is closed; instead it remains active so you that can connect again via the Connect menu.