Using the Terminal
Using the Terminal in Batch Mode
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

For some operating systems, you can run the Terminal from the command line (for example, the DOS window). This chapter is organized as follows:

Escape Characters in Windows
The various versions of Microsoft Windows interpret the caret character (^) and percent character (%) differently from one another. A specific line of text may also be interpreted differently depending on whether you type it into a “batch” window (DOS prompt) or include it as input in a batch script.
The following table gives the different input sequences required to represent the following line on different operating systems:
cterm /console=cn_ap:cache[USER]:^%D
Operating System Differences
Operating System Environment Rule Input Sequence
Windows 7 DOS prompt No escaping needed cterm /console=cn_ap:cache[USER]:^%D
Windows NT, Windows 2000, Windows XP DOS prompt Double caret (^) characters cterm /console=cn_ap:cache[USER]:^^%D
Windows 7, Windows NT, Windows 2000, Windows XP Batch file Double caret (^) characters
Double percent (%) characters
cterm /console=cn_ap:cache[USER]:^^%%D
Windows 9x, Windows ME DOS prompt or batch file Double percent (%) characters cterm /console=cn_ap:cache[USER]:^%%D
For other operating systems, consult the documentation for the relevant operating system.
The Batch Command Line
You can invoke the Terminal from the DOS command line (cmd.exe, to be precise). The general form of the command line is:
    cterm Arg1 Arg2 ... ArgN ScriptFilePath
Where:
Invoking the Terminal in Batch Mode
Item Meaning
cterm Invokes the Terminal application. If the Windows environment variable PATH includes the location of the Caché binaries, then use the command name cterm or cterm.exe. Otherwise, you must use a full or partial path. For a default installation of Caché, the binaries are in the directory install-dir\Bin
Arg1 ... ArgN Control arguments (described in the next section).
ScriptFilePath The location of the script file.
Control Arguments
Several arguments modify the starting environment for the Terminal session. Some of these are reserved for internal use and are not described here. The most useful arguments are as follows.
Note:
If you start the Terminal with either the /console or the /server control argument, the Connect menu item is not shown.
/console=<ConnectString>
This argument specifies both the type of connection and the additional data needed to make the connection. There are two types: TELNET connections and connections to local console applications.
Note:
You cannot specify both /console and /server arguments.
/console=cn_iptcp:<HostAddr>
This specifies the target system with which the Terminal is to interact over a TELNET connection. This is useful for running a script on the local machine. In this case, you specify the local machine IP address and port as HostAddr. For example:
    cterm /console=cn_iptcp:127.0.0.1[23]
/console=cn_ap:<Instance>[<Namespace>]
You can open a Terminal prompt. For example:
    cterm /console=cn_ap:cache[USER]
This line opens a Terminal session and switches to the given namespace.
In this case, the instance name is cache, and the namespace name is USER.
The namespace name is optional. If it is not supplied, the default namespace is used.
/console=cn_ap:<Instance>[<Namespace>]:<Routine>
You can also execute routines from a batch file. For example, assume that the following appears as a line in a batch (.bat) file for use in Windows 7:
    cterm /console=cn_ap:cache[USER]:^^%%D
This line starts the given instance (if it is not already running), opens a Terminal session, switches to the given namespace, executes the given routine. When the routine ends, the Terminal session is closed.
In this case, the instance name is cache, and the namespace name is USER. The routine name is ^%D (which prints out the current date). Be sure to read Escape Characters in Windows,” earlier in this chapter.
The namespace name is optional. If it is not supplied, the default namespace is used.
/server=<ServerName>
This argument specifies the name of the server to use for a secure connection between this Terminal session and the given server.
    cterm /server=ServerName
For ServerName, specify a Caché server. To see the list of available servers, select the InterSystems Launcher and then select Preferred Server. The system then displays a list of servers.
Make sure of the following, on platforms other than UNIX:
On UNIX®, the server does not need to be running, but you will log in to a shell, not directly in to Caché.
Note:
You cannot specify both /console and /server arguments.
/size=RowsxCols
This argument gives the initial size of the Terminal screen, in terms of rows and columns. Each of Rows and Cols must be an unsigned integer. The x that separates them is required as shown. No spaces are permitted in the control argument.
The allowed ranges for Rows and Cols are:
/pos=(X,Y)
This argument gives the initial origin of the Terminal screen in the display device window in pixels. Both X and Y must be unsigned integers. The parentheses around the pair and the comma separator are required. No spaces are permitted in the control argument.
Note:
It is possible to place a window outside the displayed area by using values for X and Y that are larger than the size of the display device.
/ppos=(Xpct,Ypct)
This argument gives the initial origin of the Terminal screen in the display device window in terms of a percentage of the display area. Both Xpct and Ypct must be unsigned integers. The parentheses around the pair and the comma separator are required. No spaces are permitted in the control argument.
The allowed ranges for XPct and Ypct are:
That is, the window origin cannot be placed above and to the left of the device origin. Nor can it be placed more than 40% down or across the display device.
/UnbufferedLogging
This argument causes output to be written immediately to the log file when logging is active instead of being buffered. This may be useful if another process is inspecting the output of the log file.
Examples
This section uses the example script shown earlier in this document, and shows two ways to run it.
Running a Script in Batch Mode
This example uses the basic debugging routine ^%STACK to display information about the current user and the Terminal process. If the script commands are stored in C:\TestScript.scr, you can run the example by typing into a DOS command window:
C:\CacheSys\Bin\cterm.exe /console=cn_iptcp:127.0.0.1[23] C:\TestScript.scr
Running a Script Interactively
You can invoke the previous routine in a Terminal session as follows:
C:\CacheSys\Bin\cterm.exe /console=cn_ap:cache[USER]:^^%STACK
You can manually provide the responses that the script supplied in that example. When you reply to the prompt Stack Display Action: by pressing the Enter key, the Terminal window closes.