TCL and General User Commands

This topic introduces the Terminal Command Language, describing:

It contains a list of general user commands that are not described elsewhere in the Reality documentation and provides a detailed description of each. Included are TCL commands for:

Introduction to the Terminal Control Language

The Terminal Control Language (TCL) is the primary interface between database users and Reality processors. Processors are executed by typing a command input statement at the TCL colon prompt (:) and pressing the return key.

Note

If you are running the evaluation version of Reality, the TCL colon prompt will be prefixed by the text "Eval".

The following types of TCL command are supported by Reality:

Command definition items

TCL commands available for use in an account are defined by command definition items in the account's Master Dictionary (MD). The item-id of a command definition item is the name of the command it defines. The first attribute of the definition item specifies the type of command. Proc definition items contain PQ or PQN in attribute 1. All other command definition items have P or V as the first character in attribute 1. Some have a second character that defines special functions that have to be performed by Reality software for that particular command.

Synonym command definition items

A synonym command definition item is identified by a V in attribute 1. A synonym definition item can be created by the user to reference a standard command definition item, providing an alternative name that can be entered at TCL to execute the command. The synonym item-id chosen must be unique within the MD. With V in the first attribute, the second attribute contains the item-id of the referenced command.

Further Information

The topic Command Definition Items details all types of command definition items.

TCL input processing

The command input statement entered at the TCL colon prompt must begin with a command name which matches the item-id of one of the command types listed previously. Each input statement can include several parameters, but only one command name. The statement is processed by TCL after return is pressed. When processing is complete, Reality re-displays the TCL colon prompt.

The TCL processor analyses an input statement by first looking up the verb (the first word of the input statement) in:

  1. The command definition item-ids in the MD.
  2. The alternate verbs file.

  3. The MD of the GLOBAL.MD account.

    Note

    If the verb is prefixed with a tilde (~), it is only looked up in the GLOBAL.MD account. This allows the user to intercept system commands but call the global versions from their programs.

    This behaviour can be changed by setting the INHIBIT~ environment option, so that existing commands with verbs that start with tildes can still be used.

Case sensitivity at TCL

In general, the TCL processor is sensitive to the case of commands you enter. However, if the command cannot be found and the first character is in lower case, the entire command line except for any quoted strings is converted to upper case and the search is repeated. For example, if you enter

edelete test "$testitem"

this will be converted to

EDELETE TEST "$testitem"

Notes:

  • Only the command line is converted in this way. If a command prompts you for additional parameters, these must be entered using the correct case.
  • The MD contains both upper and lower case versions of commands that access the host operating system, such as DIR-VIEW, SYS and T-DEVICE. This is to help prevent changing the case of any case sensitive host paths and filenames.
  • If the account's MDClosed Master Dictionary - the dictionary file that defines an account. It contains items that point to the code executed by all the TCL commands, to SYSTEM accounts, and to other accounts by means of Q-pointers. The MD also includes all File Definition Items for the account and other items. is case-insensitive (see Item-id Case Sensitivity), a valid command will be found in the MD whatever its case; the case of the command line will therefore not be changed.

  • To convert a complete command, including any quoted strings, to upper case, enter the TCL stacker and use the MU Editor command. Then re-execute the modified command. For example:

    :edelete test "$testitem"

'$testitem' not on file.
[430] No items deleted.
:.
Top
001 edelete test "$testitem"
.MU
001 EDELETE TEST "$TESTITEM"
.FI

:EDELETE TEST "$TESTITEM"

1 Items deleted.
:

Command options

Options are letters that modify the action of the command. They must normally be placed at the end of the sentence, following an open parenthesis character; a closing parenthesis is optional. Options can be separated by commas, but not by spaces.

Note

If you set the EMBEDDED.OPTION environment option you can place options in the middle of the command line. In this case, the closing parenthesis is mandatory.

An option not used by a particular command is ignored. The description of each TCL command lists the options that are recognised by that command.

Numeric options

In addition to letters, options can include up to two integer numbers separated by a hyphen. Hexadecimal numbers can be entered by preceding them with a dot (if the second number is hexadecimal, the hyphen can be omitted).

Examples:
(AB23C

Specifies the option letters A, B and C, and the integer option 23 decimal.

(AB.F-.1C)

Specifies the option letters A and B, and the integer options F and 1C hexadecimal. Note that because the letter C follows a dot, it is interpreted as part of the hexadecimal number 1C.

Line continuation

When you are typing characters in response to the TCL prompt, the system allows you to enter up to 240 characters before it performs an automatic linefeed. However, you can extend a line by pressing a line continuation key combination.

To specify line continuation, hold down the ctrl key and press the underscore key (_); this may require you to hold down the shift key as well as CTRL. Then press the return key.

Note

If a space is required at the line continuation, this must be included as if the line continuation had not been entered.

TCL-I commands

TCL-Icommands execute directly and do not require a fixed format of parameters to be entered after the command, unlike the TCL-II commands described next. The only rule for a TCL-I input statement is that it must begin with a TCL-I command and end with return. Some TCL-I commands do accept parameters or have options; others have no parameters or options. The TCL-I syntax is as follows:

command {parameter}... {(options}

where:

command specifies the operation.

parameter is required for some TCL-I commands.

Most TCL-I commands either allow no options or allow only the following:

H Heading. Suppresses default heading line.

N No Page. Inhibits automatic pause at end of screen.

P Print. Sends output to the Spooler.

Examples of TCL-I commands are ADDX, BLOCK-PRINT and LISTVERBS.

TCL-II commands

TCL-II commands execute the TCL-II processor first before transferring control to the specific execution code. These commands require certain parameters always to be supplied. These must comprise a file specifier followed by one or more item-ids, then optionally, one or more options. The syntax must be as follows:

command file-specifier item-list {(options}

where:

command Specifies the operation.

file-specifier Specifies the file to be processed. For details, see General Conventions.

item-list One or more item-ids separated by spaces. If an item-id contains embedded blanks or parentheses, it must be surrounded by single or double quotes.

To specify all the items in a file, enter an asterisk (*) for the item-list.

You can also use an active select list instead of an item list. This is supplied by a command that generates a select list executed immediately before the TCL-II command. For more information, refer to the topic Item-List-Generating Commands.

If you do not provide any type of item list, the processor prompts you for one.

Unless otherwise noted, TCL-II commands support the following options.

N No Page. Inhibits automatic pause at end of screen.

P Print. Sends output to the Spooler.

Several options can be specified at the same time. For example, (IP.

Examples of TCL-II commands are COPY, COMP and PRINT-ERR.

English commands

English commands are entered at TCL, but control is passed to the English processor for the command to be executed. An English input statement consists of a command and a file specifier followed by a number of optional clauses. Generally, the clauses can be entered in any sequence. For detailed information on constructing an English input statement, refer to the The English Sentence.

Item-list-generating commands

TCL and English commands can be used in conjunction with list-generating commands. These commands generate a select list that can be used to supply an item list to an immediately following TCL-II or English command. Alternatively, the list can be saved via SAVE-LIST or NEW-SAVE-LIST for later retrieval via the GET-LIST or NEW-GET-LIST command respectively.

The active Select list is indicated by a change from the usual TCL prompt, the colon (:), to the select prompt, the 'greater than' (>) symbol. The next command you enter at this new prompt uses the active list.

For example, to copy all of the items in the file BP that begin with the letter B to another file called NEWBP, type the following: 

:SELECT BP = 'B]'
26 ITEMS SELECTED.
>COPY BP
TO:(NEWBP
26 ITEMS COPIED

Item list processing commands

Other commands that enable lists to be managed are listed in List Processing Commands.

Cataloged DataBasic programs

Commands that are cataloged DataBasic programs are executed by entering the name of the program at the TCL prompt (:). The syntax will depend on the program.

A compiled program is cataloged using the CATALOG command; this loads the program object item into a system file called POINTER-FILE and creates a command definition item in the MD of the account in which the program is cataloged. The command definition item points to the object item. For more information, refer to Introduction to DataBasic.

Procs

These commands are executed by typing the name of the Proc at the TCL prompt (:). The syntax will depend on the Proc. Some system commands are Procs.

Proc commands have the code PQ or PQN in attribute one of their Proc definition items. You can create new commands by writing your own Procs.

Creating new Proc commands

When creating new Proc commands two conventions should be observed.

For more information, refer to the Proc Reference.

TCL macros

TCL macros allow users to perform simple batch tasks formed by combining TCL commands. Macros are items in the MD of an account and can be created with any of the Reality editors, or by saving commands from the TCL command stack.