docs.intersystems.com
InterSystems IRIS Data Platform 2019.2  /  Using the Terminal

Using the Terminal
Introduction to the Terminal
Previous section           Next section
InterSystems: The power behind what matters   
Search:  


The Terminal is a simple command-line interface for entering ObjectScript commands and displaying current values. It is useful during learning, development, and debugging.
This chapter discusses the following topics:
Note:
If the Terminal displays a dialog box with the message Spy Mode On, this means that you have accidentally pressed Alt+Shift+S. To exit this mode, press Alt+Shift+S again. This mode is not for general use and is not documented.
Also, if the Terminal appears to be unresponsive, you may have pressed Ctrl+S, which pauses the automatic scrolling. If so, press Ctrl+Q to resume.
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:
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.
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. For example:
d ^myroutine
set dirname = "c:\test"
set obj=##class(Test.MyClass).%New()
write obj.Prop1
Note:
The Terminal implicitly issues the Use 0 command after each line you enter. This means that if you issue a Use command to direct output to some other device, that command is essentially ignored.
Also, large input buffers may defer the action of keys that attempt to stop the input flow such as Ctrl-C or Ctrl-S. This is also dependent on processor and connection speed. A special effort was made to respond to keystrokes before host input.
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.
Note:
The installation of ZWELCOME into the %SYS namespace requires an individual with administrator privileges and write access to the IRISSYS database.
Caution:
The ZWELCOME routine executes in the %SYS namespace with an empty $USERNAME and with $ROLES set to %ALL. Take care to ensure that the failure modes of ZWELCOME are benign. Also, this routine should not modify the $ROLES variable.
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 ZNSPACE command (which has a short form of ZN):
USER>ZN "SAMPLES"
SAMPLES>
The argument for the ZNSPACE command is a single string that is the name of the namespace to change to. If you enter an invalid namespace name, ZNSPACE throws a <NAMESPACE> error. See the ZNSPACE 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.
The SQL and MDX Shells
In the Terminal, you can use shells that enable you to query data in various ways. When you use any of these shells, the prompt changes as shown in the table below:
Shell Change in the Prompt Also See
SQL [SQL] prefix is added Using the SQL Shell Interface” in Using InterSystems SQL
TSQL [SQL] prefix is added Using the TSQL Shell in Transact-SQL (TSQL) Migration Guide
MDX Prompt becomes >> MDX Shell in Introduction to InterSystems IRIS Business Intelligence
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.
Customizing the Terminal Prompt
To customize the default Terminal prompt, use the Management Portal to set the configuration option TerminalPrompt, which controls the Terminal prompt. This option is available in the Management Portal. To find it, select System Administration > Configuration > Additional Settings > Startup. For example, the Terminal prompt can include the configuration name of your system.
Interrupting Execution in the Terminal
To interrupt the Terminal and stop any foreground execution, use one of the following key combinations:
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:
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.


Previous section           Next section
Send us comments on this page
View this book as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-08-23 06:48:00