Using the Caché Terminal
Introduction to the Caché Terminal
The Caché Terminal is a simple command-line interface for entering Caché commands and displaying current values. It is useful during learning, development, and debugging.
This chapter discusses the following topics:
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
User Account That Owns the Terminal Process
In Caché versions 2015.2 and later, the Caché process is owned by the user that is logged in to Windows and is running the Terminal program (cterm.exe
In Caché versions 2015.1 and earlier:
Beginning with Windows Vista, and including Windows Vista, Windows Server 2008, and Windows 7, the Caché process that serves the Terminal connection is owned by the user account in which the Caché control service runs.
Before Windows Vista, the Caché process is owned by the user that is logged in to Windows and is running the Terminal program (cterm.exe
In all cases, all environment variables and shared drive letter designations are those defined by the user that is running 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 prompt displayed in this window indicates the namespace in which you are currently working. For example:
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.
The Terminal was designed to work with Caché applications. It uses two methods to communicate with Caché: local and network. The title bar indicates the communication mode currently in use.
Local communication is used when the Terminal communicates with the Caché server with which it was installed. In this case, the title bar displays Cache TRM:pid(instancename)
is the process ID of the Caché process with which the Terminal is communicating.
is the Caché instance in which the process is running.
Network communication uses the TELNET protocol over TCP/IP to communicate with either a Windows Caché server or with a UNIX® or OpenVMS host. In this case, the title bar displays (server NT Caché Telnet)
is the host name of the remote server.
The communications stack for Caché is Winsock. Winsock is a network programming interface for Microsoft Windows which is based on the socket paradigm popularized in the Berkeley Software Distribution (BSD). The host entry can be either from the local file, an IP address, or, if the Winsock implementation has access to a name server, a general host name. The host name may be followed by an optional #nnn to specify a nonstandard port number.
Errors reported from this communications mode are the names of the Winsock error codes. For example, WSAECONNREFUSED
means the connection was refused.
In the Terminal, you can enter Caché ObjectScript commands of all kinds. For example:
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
. 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 a Caché command to the Terminal, as if you had typed it manually.
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.
The installation of ZWELCOME
into the %SYS
namespace requires an individual with administrator privileges and write access to the CACHESYS
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
Here is a simple example:
ZWELCOME() PUBLIC ;
Set ME = ##class(%SYS.ProcessQuery).%OpenId($JOB)
Write "Now: ", $ZDATETIME($HOROLOG, 3, 1), !
Write "Pid/JobNo: ", ME.Pid, "/", ME.JobNumber, !
Write "Priority: ", ME.Priority, !
The command prompt displays the current namespace, such as:
There are several ways to change namespaces in the Terminal:
Using the ZNSPACE Command
You can change to a new namespace with the ZNSPACE
command (which has a short form of ZN
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 Caché ObjectScript Reference
for more information.
You can change to a new namespace with the ^%CD
(change directory) routine:
You're in namespace USER
Default directory is c:\intersystems\cache\mgr\user\
routine prompts for a new namespace to change to. The namespace name is not case sensitive. If you enter ?
at the prompt, ^%CD
displays a list of available namespaces. If you enter an invalid namespace name, ^%CD
presents an error message.
As noted previously, the Terminal prompt 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 within a transaction, a prefix is appended to the prompt to indicate 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 Caché ObjectScript command TSTART
, the prompt changes as follows:
If you exit the Terminal, that rolls back the transaction.
If an error occurs, a suffix is added to the prompt to indicate the program stack level. For example:
Current settings :-
No current settings
Compiler is NEW
To exit the TSQL shell, enter the ^
To access the MV shell, type MV
and press Enter
. The prompt is then displayed with a colon (:
) at the end rather than a right angle bracket (>
), as follows:
If the MV shell has not yet been initialized, you may see messages before this prompt.
To exit the MV shell, enter the Quit
Do not open another MV shell from within an MV shell.
In the Terminal, you can also open various operating-system shells. To do so, type !
and press Enter
. The Terminal then opens your default operating-system shell, and the prompt shows the working directory. For example:
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
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:
To exit the Terminal, do either of the following:
This causes 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 Cache 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